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

docs(summary): declare encoach_backend_v4 + encoach_frontend_v4 as repos of record

Browse Source 
Flip the source-of-truth model: the two split repos at git.albousalh.com are
now the authoritative origins for each half of the stack; this workspace
(`odoo19/`) is demoted to a developer working tree / full-stack monorepo
mirror.

- Header banner rewritten: canonical repos stated up front with links; mark
  the monorepo mirror as secondary.
- §6 restructured into 6.1–6.8: layout diagram, reordered remotes table
  (backend-v4 + frontend-v4 first), feature workflow that ends in publishing
  to the canonical repos (monorepo push is now optional), mandatory
  `git subtree split + push` commands for both halves, per-repo "what's
  shipped / what's not", VPS team-lead quickstart, safety rules, creds.

Made-with: Cursor
This commit is contained in:
Yamen Ahmad
2026-04-19 03:26:12 +04:00
parent 7f1f058e8f
commit 7737f6def5
1 changed files with 111 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
docs/PROJECT_SUMMARY.md
View File

@@ -1,11 +1,12 @@
# EnCoach Platform — Project Summary # EnCoach Platform — Project Summary
> Last updated: 2026-04-19 | **This repo (`odoo19/`) is the single source of truth — main working branch: `v4`.** > Last updated: 2026-04-19 | **Canonical repos: [`encoach_backend_v4`](https://git.albousalh.com/devops/encoach_backend_v4) (backend) + [`encoach_frontend_v4`](https://git.albousalh.com/devops/encoach_frontend_v4) (frontend), branch `main`.**
> >
> All feature work is committed here first, then published to the two split repos (`encoach_frontend_v4`, `encoach_backend_v4`) that the team lead deploys on the VPS. See **§6 Git Remotes & Repositories** for the exact workflow. > This workspace (`odoo19/`) is a **developer monorepo / working tree only** — it conveniently contains both halves side-by-side for local development and testing. The two split repos above are the **authoritative origins** for each half: every change must be published to them (via `git subtree split + push`) before the team lead can deploy. See **§6 Git Remotes & Repositories** for the exact workflow.
> **Latest events:** > **Latest events:**
> - **2026-04-19 (release to VPS repos):** Pushed the accumulated institutional + support + training work to all three remotes. Monorepo `origin/v4` → `98b9837a`. Frontend split → `encoach_frontend_v4/main` (`b78124bb..435930a8`, 403 files, clean fast-forward). Backend split → `encoach_backend_v4/main` (`74d83af5..6ec68160`, 420 files, clean fast-forward). `.gitignore` updated to exclude `pgdata_bak_*/`, `frontend/.vite/`, `frontend/dist/`, `frontend/node_modules/` so the 674 MB of local pgdata backups never leak into a push. See §6. > - **2026-04-19 (repos-of-record reorganization):** Declared `encoach_backend_v4` and `encoach_frontend_v4` as the canonical origins for their respective halves; the monorepo `encoach_backend_new_v2/v4` is now a secondary working-tree mirror kept only for history/convenience. §6 rewritten around this model.
> - **2026-04-19 (release to VPS repos):** Pushed the accumulated institutional + support + training work. Frontend canonical → `encoach_frontend_v4/main` (`b78124bb..435930a8`, 403 files, clean fast-forward). Backend canonical → `encoach_backend_v4/main` (`74d83af5..6ec68160`, 420 files, clean fast-forward). Monorepo mirror → `v4` (`98b9837a`). `.gitignore` now excludes `pgdata_bak_*/`, `frontend/.vite/`, `frontend/dist/`, `frontend/node_modules/` so the 674 MB of local pgdata backups never leak into a push. See §6.
> - **2026-04-18 (training section):** Built the Training section end-to-end — the `Vocabulary` and `Grammar` pages (previously pure hard-coded mocks) are now wired to real Odoo data with CRUD, search, level filtering, and per-user progress tracking. New `encoach.vocab.item` / `encoach.vocab.progress` / `encoach.grammar.rule` / `encoach.grammar.progress` models + `/api/training/vocabulary` and `/api/training/grammar` controllers. 26/26 API write-flow actions passing (`test_training_flows.py`); both pages verified live in-browser. See §19. > - **2026-04-18 (training section):** Built the Training section end-to-end — the `Vocabulary` and `Grammar` pages (previously pure hard-coded mocks) are now wired to real Odoo data with CRUD, search, level filtering, and per-user progress tracking. New `encoach.vocab.item` / `encoach.vocab.progress` / `encoach.grammar.rule` / `encoach.grammar.progress` models + `/api/training/vocabulary` and `/api/training/grammar` controllers. 26/26 API write-flow actions passing (`test_training_flows.py`); both pages verified live in-browser. See §19.
> - **2026-04-18 (support section):** Built the Support section end-to-end — the `Tickets`, `Payment Record`, and `Settings` pages are now wired to real Odoo data (they were previously mocks/404s). New `encoach.ticket` model + full CRUD controller, `/api/payment-records` deriving from `op.student.fees.details` + `account.move`, `/api/codes` + `/api/packages` + `/api/grading-config` powering the Settings tabs. 29/29 API write-flow actions passing (`test_support_flows.py`); all 3 pages verified live in-browser. See §18. > - **2026-04-18 (support section):** Built the Support section end-to-end — the `Tickets`, `Payment Record`, and `Settings` pages are now wired to real Odoo data (they were previously mocks/404s). New `encoach.ticket` model + full CRUD controller, `/api/payment-records` deriving from `op.student.fees.details` + `account.move`, `/api/codes` + `/api/packages` + `/api/grading-config` powering the Settings tabs. 29/29 API write-flow actions passing (`test_support_flows.py`); all 3 pages verified live in-browser. See §18.
> - **2026-04-18 (institutional pages write-flow):** API-level write-flow sweep across all 14 institutional admin pages — **44/44 actions passing** (CREATE / EDIT / DELETE / WORKFLOW). Numerous backend gaps fixed: missing DELETE routes added (admission-registers, admissions, result-templates, student-leaves), lesson/library detail endpoints added, custom `encoach.asset` model introduced to replace the missing `op.asset`, marksheet generate endpoint aliased for Odoo 19's `generate_result`, fees `create-invoice` auto-wires the product income account via Odoo 19's JSONB property storage, academic-year DELETE now cascades dependent terms. See §17. > - **2026-04-18 (institutional pages write-flow):** API-level write-flow sweep across all 14 institutional admin pages — **44/44 actions passing** (CREATE / EDIT / DELETE / WORKFLOW). Numerous backend gaps fixed: missing DELETE routes added (admission-registers, admissions, result-templates, student-leaves), lesson/library detail endpoints added, custom `encoach.asset` model introduced to replace the missing `op.asset`, marksheet generate endpoint aliased for Odoo 19's `generate_result`, fees `create-invoice` auto-wires the product income account via Odoo 19's JSONB property storage, academic-year DELETE now cascades dependent terms. See §17.
@@ -158,112 +159,157 @@ odoo19/
## 6. Git Remotes & Repositories ## 6. Git Remotes & Repositories
> **This monorepo (`/Users/yamenahmad/projects2026/odoo/odoo19/`) is the canonical source of truth.** > **Canonical (repos-of-record):**
> All feature work lands here on the `v4` branch. The two split repos > - Backend → **[`encoach_backend_v4`](https://git.albousalh.com/devops/encoach_backend_v4.git)** — branch `main`
> (`encoach_frontend_v4`, `encoach_backend_v4`) are **publish targets only** — the > - Frontend → **[`encoach_frontend_v4`](https://git.albousalh.com/devops/encoach_frontend_v4.git)** — branch `main`
> team lead (Talal / devops) clones them on the VPS and runs `docker compose up`. >
> Never commit directly into the split repos; always publish from this monorepo > These are the repositories the team lead (Talal / devops) clones on the VPS and
> via `git subtree split + git push`. > builds with `docker compose up -d --build`. **All production / staging code
> lives here.**
>
> This workspace (`odoo19/`) is a **developer monorepo / working tree** — a
> convenience folder that holds both halves side-by-side so a single developer
> can run the full stack locally. It is **not** the source of truth: every change
> must be published to the two canonical repos above via `git subtree split + push`
> before it counts as merged.
### 6.1 Repository Layout ### 6.1 Repository Layout
``` ```
odoo19/ ← THIS repo (single source of truth, branch v4) odoo19/ ← developer working tree (NOT source of truth)
├── backend/ → published to encoach_backend_v4/main ├── backend/ → published to encoach_backend_v4/main (authoritative)
│ ├── custom_addons/ │ ├── custom_addons/
│ ├── Dockerfile │ ├── Dockerfile
│ ├── docker-compose.yml │ ├── docker-compose.yml
│ └── requirements.txt │ └── requirements.txt
├── frontend/ → published to encoach_frontend_v4/main ├── frontend/ → published to encoach_frontend_v4/main (authoritative)
│ ├── src/ │ ├── src/
│ ├── public/ │ ├── public/
│ ├── Dockerfile, vite.config.ts, package.json, … │ ├── Dockerfile, vite.config.ts, package.json, …
└── docs/ → stays in the monorepo only └── docs/ → lives only in this workspace
``` ```
### 6.2 Remotes Configured on This Clone ### 6.2 Remotes Configured on This Clone
Listed in order of importance. The two bold rows are the **repos of record**;
everything else is either a secondary mirror or legacy.
| Remote | URL | Role | | Remote | URL | Role |
|--------|-----|------| |--------|-----|------|
| **`origin`** | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` | **Canonical monorepo** — the `v4` branch tracks `origin/v4`. Every commit goes here first. | | **`backend-v4`** | `https://git.albousalh.com/devops/encoach_backend_v4.git` | **Canonical backend** — branch `main`. VPS deploy target. |
| `backend-v3` | `https://git.albousalh.com/devops/encoach_backend_new_v3.git` | Legacy v3 monorepo mirror (rarely used) | | **`frontend-v4`** | `https://git.albousalh.com/devops/encoach_frontend_v4.git` | **Canonical frontend** — branch `main`. VPS deploy target. |
| `frontend-v3` | `https://git.albousalh.com/devops/encoach_frontend_new_v3.git` | Legacy v3 frontend mirror (rarely used) | | `origin` | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` | Secondary monorepo mirror (branch `v4`). Handy for a full-tree backup but **not** the source of truth. |
| **`backend-v4`** | `https://git.albousalh.com/devops/encoach_backend_v4.git` | **VPS deploy target — backend only** (hoisted contents of `backend/`) | | `ip-origin` | `https://5.189.151.117/devops/encoach_backend_new_v2.git` | IP fallback for `origin` when DNS is flaky. |
| **`frontend-v4`** | `https://git.albousalh.com/devops/encoach_frontend_v4.git` | **VPS deploy target — frontend only** (hoisted contents of `frontend/`) | | `backend-v3` | `https://git.albousalh.com/devops/encoach_backend_new_v3.git` | Legacy v3 monorepo mirror — rarely used. |
| `ip-origin` | `https://5.189.151.117/devops/encoach_backend_new_v2.git` | IP fallback for `origin` when DNS is flaky | | `frontend-v3` | `https://git.albousalh.com/devops/encoach_frontend_new_v3.git` | Legacy v3 frontend mirror — rarely used. |
> The remote names `backend-v4` / `frontend-v4` pre-date this reorg; conceptually
> treat them as `origin-backend` / `origin-frontend`. Feel free to add aliases
> with `git remote rename` if you prefer different names.
### 6.3 Feature Development Workflow ### 6.3 Feature Development Workflow
Everything is edited inside this workspace, but a change is only **merged**
once it lands on `main` of the two canonical repos.
```bash ```bash
# 1. Create a feature branch off v4 # 1. Start from clean workspace synced with canonical
git checkout v4 && git pull origin v4 git checkout v4
git pull origin v4 # optional: keep monorepo mirror in sync
# 2. Create a feature branch
git checkout -b feature/<short-name> git checkout -b feature/<short-name>
# 2. Make changes, commit small and often # 3. Make changes, commit small and often
git add <files> git add <files>
git commit -m "feat(<area>): <short description>" git commit -m "feat(<area>): <short description>"
# 3. Merge back to v4 (or open a PR if repo has protection rules) # 4. Merge back onto v4 (or open a PR if branch protection is enabled)
git checkout v4 git checkout v4
git merge --no-ff feature/<short-name> git merge --no-ff feature/<short-name>
# 4. Push monorepo # 5. Publish to the CANONICAL repos (mandatory — see §6.4)
git push origin v4 # This is what the team lead / CI will see.
# 5. Publish to VPS deploy targets (see §6.4) # 6. (Optional) push the monorepo mirror for a full-tree backup
git push origin v4
``` ```
### 6.4 Publishing to the Split VPS Repos (backend-v4 / frontend-v4) ### 6.4 Publishing to the Canonical Repos (MANDATORY)
The split repos expect a **flat tree** (no `backend/` or `frontend/` prefix). The canonical repos expect a **flat tree** (no `backend/` or `frontend/`
Use `git subtree split` to carve each subdirectory's history, then push to prefix). Use `git subtree split` to carve each subdirectory into its own
`main` on the split remote. This is a fast-forward if nothing strange has been parallel history, then push to `main`. These commands produce clean
pushed to the split repos from elsewhere. fast-forwards when nothing has been pushed directly to the canonical repos
from elsewhere — which is the invariant we enforce.
```bash ```bash
# ── Publish FRONTEND ──────────────────────────────────────────────────── # ── Publish BACKEND → encoach_backend_v4 ─────────────────────────────────
git subtree split --prefix=frontend HEAD -b split-frontend-v4
git push frontend-v4 split-frontend-v4:main
git branch -D split-frontend-v4 # cleanup (temp branch)
# ── Publish BACKEND ─────────────────────────────────────────────────────
git subtree split --prefix=backend HEAD -b split-backend-v4 git subtree split --prefix=backend HEAD -b split-backend-v4
git push backend-v4 split-backend-v4:main git push backend-v4 split-backend-v4:main
git branch -D split-backend-v4 git branch -D split-backend-v4 # cleanup the temp branch
# ── Publish FRONTEND → encoach_frontend_v4 ───────────────────────────────
git subtree split --prefix=frontend HEAD -b split-frontend-v4
git push frontend-v4 split-frontend-v4:main
git branch -D split-frontend-v4
``` ```
If a push is rejected as non-fast-forward, fetch first and inspect: If a push is rejected as non-fast-forward, fetch and inspect before forcing:
```bash ```bash
git fetch frontend-v4 backend-v4 git fetch backend-v4 frontend-v4
git log --oneline frontend-v4/main..split-frontend-v4 # what we're adding git log --oneline backend-v4/main..split-backend-v4 # what we're adding
git log --oneline split-frontend-v4..frontend-v4/main # divergence, if any git log --oneline split-backend-v4..backend-v4/main # divergence, if any
``` ```
Only use `--force` when you have explicitly confirmed the remote `main` has Only use `--force` after confirming the remote `main` has no commits worth
nothing you want to keep (e.g. someone pushed directly and it must be keeping (e.g. someone pushed directly and it must be overwritten). Since the
overwritten). canonical repos are the source of truth, a force-push there is a **destructive
production operation** — pair it with a Slack heads-up to the team lead.
### 6.5 What Each Split Repo Contains ### 6.5 What Each Canonical Repo Contains
**`encoach_frontend_v4` (branch `main`):** everything under `frontend/` hoisted **`encoach_backend_v4` (branch `main`)** — everything under `backend/` hoisted
to repo root — `src/`, `public/`, `docs/`, `Dockerfile`, `docker-compose.yml`, to repo root:
`package.json`, `package-lock.json`, `bun.lock`, `bun.lockb`, `vite.config.ts`,
`tsconfig.*.json`, `tailwind.config.ts`, `eslint.config.js`, `index.html`,
`.env.example`, `components.json`. **Excluded:** `node_modules/`, `dist/`,
`.vite/`, `.env`, `.env.development`, `.env.production` (these are ignored by
`frontend/.gitignore`).
**`encoach_backend_v4` (branch `main`):** everything under `backend/` hoisted - `custom_addons/` (all EnCoach Odoo addons + `encoach_lms_api`)
to repo root — `custom_addons/`, `Dockerfile`, `docker-compose.yml`, - `Dockerfile`, `docker-compose.yml`, `requirements.txt`
`requirements.txt`. **Excluded:** `openeducat_erp-19.0/` is vendored locally but
**not** tracked in git — the VPS will need OpenEduCat installed separately
(either vendored into the container image, mounted from `/opt/odoo/extra_addons`,
or added to `requirements.txt` if an OpenEduCat package is used).
### 6.6 Safety Rules (DO NOT COMMIT) **Not shipped:** `openeducat_erp-19.0/` is vendored locally but not tracked in
git. The VPS needs OpenEduCat installed separately — either baked into the
container image, mounted at `/opt/odoo/extra_addons`, or installed via pip if a
package release is used. `backend/odoo.conf` is also not currently tracked; add
it in a follow-up commit if the VPS container needs a baked-in config.
Already excluded via `.gitignore` — do not try to force them in: **`encoach_frontend_v4` (branch `main`)** — everything under `frontend/` hoisted
to repo root:
- `src/`, `public/`, `docs/` (frontend docs only)
- `package.json`, `package-lock.json`, `bun.lock`, `bun.lockb`
- `Dockerfile`, `docker-compose.yml`
- `vite.config.ts`, `tsconfig.*.json`, `tailwind.config.ts`, `eslint.config.js`
- `index.html`, `components.json`, `.env.example`
**Not shipped** (ignored by `frontend/.gitignore`): `node_modules/`, `dist/`,
`.vite/`, `.env`, `.env.development`, `.env.production`.
### 6.6 VPS Deploy — Team-Lead Quickstart
```bash
# Backend
git clone https://git.albousalh.com/devops/encoach_backend_v4.git
cd encoach_backend_v4 && docker compose up -d --build
# Frontend
git clone https://git.albousalh.com/devops/encoach_frontend_v4.git
cd encoach_frontend_v4 && cp .env.example .env # set VITE_API_BASE_URL
docker compose up -d --build # or: npm ci && npm run build
```
### 6.7 Safety Rules (DO NOT COMMIT)
Already excluded via `.gitignore` — do not force them in:
- `pgdata/`, `pgdata_bak_*/` — PostgreSQL data directories (up to ~700 MB) - `pgdata/`, `pgdata_bak_*/` — PostgreSQL data directories (up to ~700 MB)
- `frontend/node_modules/`, `frontend/dist/`, `frontend/.vite/` — build artifacts - `frontend/node_modules/`, `frontend/dist/`, `frontend/.vite/` — build artifacts
@@ -271,11 +317,11 @@ Already excluded via `.gitignore` — do not try to force them in:
- `.venv/`, `venv/`, `.conda-envs/` — Python virtualenvs - `.venv/`, `venv/`, `.conda-envs/` — Python virtualenvs
- `*.zip`, `*.tar.gz` — archives - `*.zip`, `*.tar.gz` — archives
`odoo.conf` at the repo root IS tracked (it's your local Mac dev config). `odoo.conf` at the workspace root IS tracked (local Mac dev config, harmless).
`backend/odoo.conf` is **not** currently tracked — if the VPS container needs `backend/odoo.conf` (container-friendly) is **not** tracked; add it in a
a baked-in config, add it in a dedicated commit. follow-up if the VPS image needs it baked in.
### 6.7 Git Credentials ### 6.8 Git Credentials
Stored in macOS Keychain for `git.albousalh.com`: Stored in macOS Keychain for `git.albousalh.com`:
- Username: `yamen` - Username: `yamen`