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)

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+

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 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