# EnCoach Backend v2 — Odoo 19 Adaptive Learning Platform

The Odoo 19 backend for the **EnCoach** adaptive learning and institutional LMS platform. Provides ~377 REST API endpoints serving a React 18 SPA frontend.

## System Overview

| Component | Detail |
|-----------|--------|
| **Framework** | Odoo 19 Community Edition |
| **Language** | Python 3.12+ |
| **Database** | PostgreSQL 16 |
| **LMS Foundation** | OpenEduCat Community (14 modules, ported to v19) |
| **Custom Modules** | 27 `encoach_*` modules |
| **AI/ML** | OpenAI GPT-4o, Whisper (local), AWS Polly, ELAI, GPTZero, FAISS |
| **Authentication** | JWT (PyJWT) |
| **Deployment** | Docker Compose |

## Module Architecture

```
new_project/
  custom_addons/           # 27 custom EnCoach modules
    encoach_api/           # REST API controllers (~120 routes)
    encoach_lms_api/       # OpenEduCat bridge API (~209 routes)
    encoach_adaptive_api/  # Adaptive learning API (~41 routes)
    encoach_resources/     # Resource library API (~7 routes)
    encoach_core/          # Users, entities, roles, permissions
    encoach_taxonomy/      # Subject > Domain > Topic taxonomy
    encoach_adaptive/      # Proficiency, learning plans, mastery
    encoach_adaptive_ai/   # AI for diagnostics, coaching, content
    encoach_exam/          # AI-powered exam engine
    encoach_ai/            # OpenAI service wrapper
    encoach_ai_generation/ # AI exam content generation
    encoach_ai_grading/    # AI grading (writing, speaking, math, IT)
    encoach_ai_media/      # TTS (Polly), STT (Whisper), ELAI avatars
    encoach_courseware/     # Chapters, materials, AI workbench
    encoach_communication/ # Discussion boards, announcements, messaging
    encoach_notification/  # Notification engine, rules, preferences
    encoach_faq/           # FAQ categories and items
    encoach_approval/      # Approval workflows, stages
    encoach_assignment/    # Exam-wrapper assignments
    encoach_classroom/     # Virtual classroom groups
    encoach_stats/         # Session tracking, statistics
    encoach_training/      # Training tips, walkthroughs, FAISS
    encoach_subscription/  # Packages, Stripe/PayPal/Paymob
    encoach_registration/  # User registration, batch import
    encoach_ticket/        # Support tickets
    encoach_sis/           # UTAS SIS integration
    encoach_branding/      # Whitelabeling
  openeducat_erp-19.0/     # 14 OpenEduCat community modules
    openeducat_core/       # Courses, batches, students, faculty
    openeducat_timetable/  # Timetable sessions
    openeducat_attendance/ # Attendance management
    openeducat_exam/       # Institutional exams, marksheets
    openeducat_assignment/ # Course assignments, submissions
    openeducat_admission/  # Admission registers, applications
    openeducat_classroom/  # Physical classrooms
    openeducat_facility/   # Facilities and assets
    openeducat_fees/       # Fee plans, student fees
    openeducat_library/    # Library media, movements, cards
    openeducat_activity/   # Student activities
    openeducat_parent/     # Parent-student relationships
    openeducat_erp/        # ERP connector
    theme_web_openeducat/  # Web theme
```

## Staging

| Service | URL |
|---------|-----|
| **Odoo Backend** | `http://5.189.151.117:8069` |
| **React Frontend** | `http://5.189.151.117:3000` |

## Branching Workflow

This repo is connected to the staging server via a Git post-receive hook.
**All deployment is automatic after code review approval.**

1. Never push directly to `main` -- branch protection will block it.
2. Push your changes to a feature branch (e.g. `feature/full-backend-v1`).
3. Open a Pull Request on Gitea targeting `main`.
4. Request review from **devops (Talal)**.
5. Once approved and merged, the staging server rebuilds and redeploys automatically.

The `.env` file is **not committed**. It lives only on the staging server at `/opt/encoach/backend-v2/.env`.

## Local Development

### Option A: Docker (easiest)

```bash
docker compose up -d
```

Open `http://localhost:8069`. First run: create a new database.

Stop: `docker compose down`

### Option B: Source (venv + PostgreSQL)

**Prerequisites:** macOS, Homebrew, Python 3.11+, PostgreSQL 15+

```bash
brew install postgresql@15 wkhtmltopdf
brew services start postgresql@15
createuser -s $(whoami)

chmod +x setup.sh
./setup.sh
./run.sh
```

Open `http://localhost:8069`.

See [MANUAL-RUN.md](MANUAL-RUN.md) for step-by-step commands.

## Related Documents

| Document | Description |
|----------|-------------|
| `ENCOACH_ODOO19_BACKEND_SRS.md` | Backend SRS v3.0 (definitive) |
| `ENCOACH_UNIFIED_SRS.md` | Unified frontend + backend SRS v2.0 |
| `ENCOACH_PRODUCT_DESCRIPTION.md` | Non-technical product description |