devops/encoach_backend_new_v2
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: add project documentation and update README

Browse Source 
- README.md: replaced generic Odoo setup guide with project overview,
  module architecture diagram, staging info, and development instructions
- docs/ENCOACH_ODOO19_BACKEND_SRS.md v3.0: complete backend SRS with
  all 41 modules and ~377 API routes marked as implemented
- docs/ENCOACH_UNIFIED_SRS.md v2.0: unified platform SRS covering
  frontend, backend, and AI stack
- docs/ODOO_DEVELOPER_HANDOFF.md: implementation-complete handoff guide
- docs/ENCOACH_PRODUCT_DESCRIPTION.md: non-technical product description
- docs/ENCOACH_SYSTEM_FEATURES_GUIDE.md: system features reference guide

Made-with: Cursor
This commit is contained in:
devops
2026-04-06 12:58:26 +04:00
parent d9f8a62886
commit bdc6598734
6 changed files with 5866 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
README.md
View File

@@ -1,140 +1,123 @@
# EnCoach Backend — v2
# 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 — but only after code review approval.**
**All deployment is automatic after code review approval.**
### How to contribute
1. Never push directly to `main` — branch protection will block it.
2. Push your changes to your feature branch (e.g. `feature/full-backend-v1`)
3. Open a Pull Request on Gitea targeting `main`
4. Request review from **devops (Talal)**
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.
### Environment
The `.env` file is **not committed**. It lives only on the staging server at `/opt/encoach/backend-v2/.env`.
---
## Local Development
# Odoo 19 Community – Local setup (macOS)
Run Odoo 19 Community on your Mac.
---
## Option A: Run with Docker (easiest)
No Python or PostgreSQL needed on your machine.
**Requirements:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) for Mac.
### Option A: Docker (easiest)
```bash
cd /Users/yamenahmad/projects2026/odoo/odoo19
docker compose up -d
```
Open **http://localhost:8069**. First time: create a new database (name, email, password).
**Test that it’s running:**
```bash
./test_odoo.sh
```
Open `http://localhost:8069`. First run: create a new database.
Stop: `docker compose down`
---
### Option B: Source (venv + PostgreSQL)
**Manual terminal guide (no scripts):** see **[MANUAL-RUN.md](MANUAL-RUN.md)** for step-by-step commands only.
---
## Option B: Run from source (venv + PostgreSQL)
## Prerequisites
- **macOS** (Sonoma, Ventura, or Monterey)
- **Homebrew** – [brew.sh](https://brew.sh) – install with:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
- **Xcode Command Line Tools** (for compilers):
```bash
xcode-select --install
```
## 1. Install PostgreSQL and wkhtmltopdf
**Prerequisites:** macOS, Homebrew, Python 3.11+, PostgreSQL 15+
```bash
brew install postgresql@15 wkhtmltopdf
brew services start postgresql@15
```
Create an Odoo database user (optional; you can also use your macOS user):
```bash
# Using your current user (no password by default on Mac)
createuser -s $(whoami)
# Or create a dedicated user with password:
createuser -s odoo
# Then in psql: ALTER USER odoo WITH PASSWORD 'odoo';
```
## 2. Run the setup script
From this directory:
```bash
chmod +x setup.sh
./setup.sh
```
This will:
- Clone Odoo 19.0 into `./odoo/`
- Create a Python virtual environment in `./venv/`
- Install Python dependencies from `odoo/requirements.txt`
## 3. Configure Odoo (optional)
Copy the example config and edit if needed:
```bash
cp odoo.conf.example odoo.conf
```
- **db_user**: your PostgreSQL user (e.g. your Mac username or `odoo`)
- **db_password**: leave empty if you use trust auth (typical on Mac)
- **addons_path**: defaults to `odoo/addons` (Community only)
## 4. Run Odoo
```bash
./run.sh
```
Or manually:
Open `http://localhost:8069`.
```bash
source venv/bin/activate
cd odoo && ./odoo-bin -c ../odoo.conf
```
See [MANUAL-RUN.md](MANUAL-RUN.md) for step-by-step commands.
- Open **http://localhost:8069**
- First run: create a new database (name, email, password, language)
- Default admin login after creating DB: email `admin`, password `admin` (if you use the demo setup)
## Related Documents
## Useful options
- **Custom database name:** `./odoo-bin -c odoo.conf -d mydb`
- **Development mode (auto-reload):** add `--dev=all` to the command
- **Install modules at start:** `-i sale,crm` (comma-separated)
## Troubleshooting
- **Port 8069 in use:** change `xmlrpc_port` in `odoo.conf` or run with `--http-port=8070`
- **PostgreSQL connection refused:** ensure it’s running: `brew services start postgresql@15`
- **Python / pip errors:** use Python 3.10, 3.11, or 3.12; create a fresh venv and run `pip install -r odoo/requirements.txt` again
| 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 |