docs(summary): declare encoach_backend_v4 + encoach_frontend_v4 as repos of record
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
@@ -1,11 +1,12 @@
|
||||
# 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:**
|
||||
> - **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 (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.
|
||||
@@ -158,112 +159,157 @@ odoo19/
|
||||
|
||||
## 6. Git Remotes & Repositories
|
||||
|
||||
> **This monorepo (`/Users/yamenahmad/projects2026/odoo/odoo19/`) is the canonical source of truth.**
|
||||
> All feature work lands here on the `v4` branch. The two split repos
|
||||
> (`encoach_frontend_v4`, `encoach_backend_v4`) are **publish targets only** — the
|
||||
> 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
|
||||
> via `git subtree split + git push`.
|
||||
> **Canonical (repos-of-record):**
|
||||
> - Backend → **[`encoach_backend_v4`](https://git.albousalh.com/devops/encoach_backend_v4.git)** — branch `main`
|
||||
> - Frontend → **[`encoach_frontend_v4`](https://git.albousalh.com/devops/encoach_frontend_v4.git)** — branch `main`
|
||||
>
|
||||
> These are the repositories the team lead (Talal / devops) clones on the VPS and
|
||||
> 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
|
||||
|
||||
```
|
||||
odoo19/ ← THIS repo (single source of truth, branch v4)
|
||||
├── backend/ → published to encoach_backend_v4/main
|
||||
odoo19/ ← developer working tree (NOT source of truth)
|
||||
├── backend/ → published to encoach_backend_v4/main (authoritative)
|
||||
│ ├── custom_addons/
|
||||
│ ├── Dockerfile
|
||||
│ ├── docker-compose.yml
|
||||
│ └── requirements.txt
|
||||
├── frontend/ → published to encoach_frontend_v4/main
|
||||
├── frontend/ → published to encoach_frontend_v4/main (authoritative)
|
||||
│ ├── src/
|
||||
│ ├── public/
|
||||
│ ├── 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
|
||||
|
||||
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 |
|
||||
|--------|-----|------|
|
||||
| **`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-v3` | `https://git.albousalh.com/devops/encoach_backend_new_v3.git` | Legacy v3 monorepo mirror (rarely used) |
|
||||
| `frontend-v3` | `https://git.albousalh.com/devops/encoach_frontend_new_v3.git` | Legacy v3 frontend mirror (rarely used) |
|
||||
| **`backend-v4`** | `https://git.albousalh.com/devops/encoach_backend_v4.git` | **VPS deploy target — backend only** (hoisted contents of `backend/`) |
|
||||
| **`frontend-v4`** | `https://git.albousalh.com/devops/encoach_frontend_v4.git` | **VPS deploy target — frontend only** (hoisted contents of `frontend/`) |
|
||||
| `ip-origin` | `https://5.189.151.117/devops/encoach_backend_new_v2.git` | IP fallback for `origin` when DNS is flaky |
|
||||
| **`backend-v4`** | `https://git.albousalh.com/devops/encoach_backend_v4.git` | **Canonical backend** — branch `main`. VPS deploy target. |
|
||||
| **`frontend-v4`** | `https://git.albousalh.com/devops/encoach_frontend_v4.git` | **Canonical frontend** — branch `main`. VPS deploy target. |
|
||||
| `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. |
|
||||
| `ip-origin` | `https://5.189.151.117/devops/encoach_backend_new_v2.git` | IP fallback for `origin` when DNS is flaky. |
|
||||
| `backend-v3` | `https://git.albousalh.com/devops/encoach_backend_new_v3.git` | Legacy v3 monorepo mirror — rarely used. |
|
||||
| `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
|
||||
|
||||
Everything is edited inside this workspace, but a change is only **merged**
|
||||
once it lands on `main` of the two canonical repos.
|
||||
|
||||
```bash
|
||||
# 1. Create a feature branch off v4
|
||||
git checkout v4 && git pull origin v4
|
||||
# 1. Start from clean workspace synced with canonical
|
||||
git checkout v4
|
||||
git pull origin v4 # optional: keep monorepo mirror in sync
|
||||
|
||||
# 2. Create a feature branch
|
||||
git checkout -b feature/<short-name>
|
||||
|
||||
# 2. Make changes, commit small and often
|
||||
# 3. Make changes, commit small and often
|
||||
git add <files>
|
||||
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 merge --no-ff feature/<short-name>
|
||||
|
||||
# 4. Push monorepo
|
||||
git push origin v4
|
||||
# 5. Publish to the CANONICAL repos (mandatory — see §6.4)
|
||||
# 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).
|
||||
Use `git subtree split` to carve each subdirectory's history, then push to
|
||||
`main` on the split remote. This is a fast-forward if nothing strange has been
|
||||
pushed to the split repos from elsewhere.
|
||||
The canonical repos expect a **flat tree** (no `backend/` or `frontend/`
|
||||
prefix). Use `git subtree split` to carve each subdirectory into its own
|
||||
parallel history, then push to `main`. These commands produce clean
|
||||
fast-forwards when nothing has been pushed directly to the canonical repos
|
||||
from elsewhere — which is the invariant we enforce.
|
||||
|
||||
```bash
|
||||
# ── Publish FRONTEND ────────────────────────────────────────────────────
|
||||
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 ─────────────────────────────────────────────────────
|
||||
# ── Publish BACKEND → encoach_backend_v4 ─────────────────────────────────
|
||||
git subtree split --prefix=backend HEAD -b split-backend-v4
|
||||
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
|
||||
git fetch frontend-v4 backend-v4
|
||||
git log --oneline frontend-v4/main..split-frontend-v4 # what we're adding
|
||||
git log --oneline split-frontend-v4..frontend-v4/main # divergence, if any
|
||||
git fetch backend-v4 frontend-v4
|
||||
git log --oneline backend-v4/main..split-backend-v4 # what we're adding
|
||||
git log --oneline split-backend-v4..backend-v4/main # divergence, if any
|
||||
```
|
||||
|
||||
Only use `--force` when you have explicitly confirmed the remote `main` has
|
||||
nothing you want to keep (e.g. someone pushed directly and it must be
|
||||
overwritten).
|
||||
Only use `--force` after confirming the remote `main` has no commits worth
|
||||
keeping (e.g. someone pushed directly and it must be overwritten). Since the
|
||||
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
|
||||
to repo root — `src/`, `public/`, `docs/`, `Dockerfile`, `docker-compose.yml`,
|
||||
`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
|
||||
to repo root:
|
||||
|
||||
**`encoach_backend_v4` (branch `main`):** everything under `backend/` hoisted
|
||||
to repo root — `custom_addons/`, `Dockerfile`, `docker-compose.yml`,
|
||||
`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).
|
||||
- `custom_addons/` (all EnCoach Odoo addons + `encoach_lms_api`)
|
||||
- `Dockerfile`, `docker-compose.yml`, `requirements.txt`
|
||||
|
||||
### 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)
|
||||
- `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
|
||||
- `*.zip`, `*.tar.gz` — archives
|
||||
|
||||
`odoo.conf` at the repo root IS tracked (it's your local Mac dev config).
|
||||
`backend/odoo.conf` is **not** currently tracked — if the VPS container needs
|
||||
a baked-in config, add it in a dedicated commit.
|
||||
`odoo.conf` at the workspace root IS tracked (local Mac dev config, harmless).
|
||||
`backend/odoo.conf` (container-friendly) is **not** tracked; add it in a
|
||||
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`:
|
||||
- Username: `yamen`
|
||||
|
||||
Reference in New Issue
Block a user