d940db075e
Audit of the admin Configuration section (FAQ Manager, Notification Rules,
Approval Config) surfaced three contract mismatches and one missing schema.
FAQ
* Backend `encoach.faq.category.audience` / `encoach.faq.item.audience`
rejected the `both` and `entity` values emitted by the FAQ Manager
UI. Widened the Selection so the UI's full vocabulary round-trips.
* FAQ item `video_url` was already accepted by the UI but silently
dropped by the controller; now persisted via a new `video_url`
field on `encoach.faq.item` and serialized on list/get responses.
Notification Rules
* Added `days_before`, `frequency`, `channel`, `entity_id` to
`encoach.notification.rule`. These are the exact fields the admin
form collects; prior to this change they were serialized into the
JSON body, ignored by the controller, and omitted from responses,
leaving the Active switch permanently off and the table columns
blank.
* Controller now translates `active` <-> `is_active` both ways so the
new frontend contract and legacy callers coexist. Missing required
fields return HTTP 400 instead of 500.
Approval Workflows
* The controller had been hand-rolling raw SQL against three tables
(`encoach_approval_workflow`, `_stage`, `_request`) that no Odoo
model declared, so the tables never existed. List() was guarded and
returned empty; create() would 500 with "relation does not exist".
* Introduced real ORM models in `encoach_exam_template/models/approval.py`
plus access rights, which auto-provision the tables on -u.
* Rewrote the controller to use ORM, added PATCH, and emitted both
`items` and `results` in the list envelope so the frontend's
PaginatedResponse reader and legacy callers both work. Step
payloads now carry `max_days`, `auto_escalate`, and
`notification_email` end to end.
* Frontend `approvalsService` and `ApprovalWorkflowConfig` updated to
send the full stage shape + `allow_bypass`, tolerate both envelope
keys, and validate at least one approver before submit.
Schema delta applied via `./run.sh -u encoach_exam_template,encoach_lms_api`.
Verified with new `test_config_flows.py`: 24/24 passing. Regression runs
on `test_support_flows.py` (29/29) and `test_training_flows.py` (26/26)
remain green.
Made-with: Cursor
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.
- Never push directly to
main-- branch protection will block it. - Push your changes to a feature branch (e.g.
feature/full-backend-v1). - Open a Pull Request on Gitea targeting
main. - Request review from devops (Talal).
- 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 |