From 0415cebde1543d8046ff8c5cefff7305e04f22de Mon Sep 17 00:00:00 2001 From: Othmane Ataallah Date: Wed, 29 Jul 2026 08:39:03 +0200 Subject: [PATCH] Update System Overview --- System-Overview.md | 180 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 179 insertions(+), 1 deletion(-) diff --git a/System-Overview.md b/System-Overview.md index 5d08b7b..4cff973 100644 --- a/System-Overview.md +++ b/System-Overview.md @@ -1 +1,179 @@ -Welcome to the Wiki. \ No newline at end of file +# System Overview โ€” the bigger picture + +*How our three projects, our tools and our Git workflow fit together. Ten minutes here saves +weeks of confusion. Diagrams are Mermaid โ€” Gitea renders them natively.* + +--- + +## 1. The whole system at a glance + +Three products, one contract, one origin server. Every dev has the SAME local setup; +Gitea is the only shared machine. + +```mermaid +flowchart TB + subgraph TEAM["๐Ÿ‘ฅ Team"] + PM["PM
backlog ยท reviews ยท decisions
owns openapi.yaml"] + DEVS["3 devs
one per repo"] + end + + subgraph GITEA["๐Ÿ—„๏ธ Gitea โ€” ORIGIN (the only shared server)"] + direction LR + RAPI["trizagenda-api
code ยท issues ยท board"] + RWEB["trizagenda-web
code ยท issues ยท board"] + RMOB["trizagenda-mobile
code ยท issues ยท board"] + RTEAM["trizagenda-team
this wiki ยท shared docs"] + end + + subgraph MACHINE["๐Ÿ’ป Each dev machine (identical, self-sufficient)"] + direction LR + CLONES["local clones
feature branches"] + RUNTIME["local runtime
API + clients + docker services
(diagram 2)"] + end + + DEVS -->|"branch โ†’ push โ†’ Pull Request"| GITEA + PM -->|"review โ‰ค 24h ยท squash merge ยท milestone tags"| GITEA + GITEA -->|"clone ยท pull --rebase daily"| CLONES + CLONES --> RUNTIME + + classDef origin fill:#e8eef7,stroke:#1a4b8c,stroke-width:2px; + class GITEA origin; +``` + +**Read it like this:** code and decisions flow through Gitea and nowhere else. Nothing is +deployed anywhere yet โ€” "the system" runs complete on every dev machine, every day. + +--- + +## 2. Runtime โ€” how the three apps exchange data (on YOUR machine) + +```mermaid +flowchart LR + subgraph CLIENTS["Clients"] + WEB["๐ŸŒ trizagenda-web
React 19 ยท Vite ยท :5173
session = httpOnly refresh cookie"] + MOB["๐Ÿ“ฑ trizagenda-mobile
Flutter ยท emulator
session = X-Refresh-Token header"] + end + + subgraph CONTRACT["๐Ÿ“œ THE contract"] + SPEC["openapi.yaml v1.2.1
single source of truth
(copy in each repo)"] + PRISM["Prism mock ยท :4010
fake API serving the spec"] + end + + subgraph APISRV["โš™๏ธ trizagenda-api โ€” Spring Boot ยท :8080/api/v1"] + REST["REST JSON
JWT Bearer 15 min
+ rotating refresh tokens"] + STOMP["WebSocket / STOMP
(M4 โ€” topic contract = spec candidate)"] + end + + subgraph COMPOSE["๐Ÿณ docker compose up -d (in trizagenda-api/)"] + PG[("PostgreSQL 16 ยท :5432
THE database โ€” schema owned by Flyway")] + REDIS[("Redis 7 ยท :6379
rate-limit & cache backend (M6)")] + MINIO[("MinIO ยท :9000 / UI :9001
S3 files โ€” avatars & attachments")] + MAILPIT["Mailpit ยท SMTP :1025
inbox UI โ†’ http://localhost:8025
catches EVERY dev email (OTP reset)"] + end + + WEB -->|"HTTP JSON ยท cookie flow"| REST + MOB -->|"HTTP JSON ยท 10.0.2.2:8080
X-Client-Type: mobile"| REST + WEB -.->|"mock-first features"| PRISM + MOB -.->|"mock-first features"| PRISM + SPEC --> PRISM + SPEC -.->|"npm run generate:api โ†’ TS types"| WEB + REST --> PG + REST --> REDIS + REST --> MINIO + REST -->|"OTP reset email"| MAILPIT + STOMP -.->|"real-time notifications (M4)"| WEB + STOMP -.->|"real-time notifications (M4)"| MOB + + classDef spec fill:#fdf3d8,stroke:#b8860b,stroke-width:2px; + class SPEC spec; + classDef future stroke-dasharray: 5 5; + class STOMP future; +``` + +**The rules that make this work:** + +- **Clients NEVER talk to the database or to each other** โ€” everything crosses the API, + which enforces roles/scope from the JWT. The only shared state between web and mobile + IS the API's database. +- **`openapi.yaml` is the treaty.** The API implements it, web generates its TypeScript + types from it, Prism mocks it, and nobody invents an endpoint outside it. Spec change = + version bump by the PM, announced, copies re-synced (`npm run generate:api` on web). +- **Mock-first:** new client features are built against Prism (:4010) so nobody waits on + the API dev; **auth is the exception โ€” always the real API**. At each milestone's + integration checkpoint, that feature flips from mock to real. + - *Mobile nuance:* the app currently ships a demo-data layer (fake repositories inside + the app) instead of Prism for non-auth domains โ€” same principle, same swap points + (see mobile `ARCHITECTURE.md` ยง6). +- **Emails never leave your machine** in dev: the API sends real SMTP to **Mailpit** + (http://localhost:8025). Production swaps in a real SMTP server via `MAIL_*` env vars โ€” + same code, different `application-*.yml` profile. +- **The database schema belongs to Flyway migrations** (`V*__*.sql` in the API repo) โ€” + never edit an applied migration; local reset = `docker compose down -v`. + +--- + +## 3. Git โ€” origin vs your machine + +Trunk-based, squash-only, tags per milestone ([full rules](https://REPLACE-GITEA/trizagenda/trizagenda-team/src/branch/main/docs/git-strategy.md)). + +```mermaid +gitGraph + commit id: "main" + commit id: "M1 starts" + branch feat/API-12-rate-limit + checkout feat/API-12-rate-limit + commit id: "feat: limiter" + commit id: "test: limiter" + checkout main + merge feat/API-12-rate-limit id: "PR 12 โ€” squash" type: HIGHLIGHT + branch feat/API-14-blacklist + checkout feat/API-14-blacklist + commit id: "feat: blacklist" + checkout main + merge feat/API-14-blacklist id: "PR 14 โ€” squash" + commit id: "checkpoint fixes" tag: "v0.1.0" +``` + +- `main` is **protected** โ€” it only moves by squash-merged PRs, so one commit = one issue, + and `git log` reads like the changelog. +- **Local machine:** your clone, your feature branches (`feat/API-12-slug`), your WIP commits + โ€” messy is fine there, the squash cleans it up. +- **Origin (Gitea):** protected `main` + your pushed branches + the PR conversation. +- **Every morning:** `git pull --rebase origin main` on your branch โ€” small daily rebases + instead of one giant conflict at PR time. +- **Milestone end:** the PM tags `main` (`v0.1.0` โ€ฆ `v1.0.0`) right after the integration + checkpoint passes. + +## 4. The daily loop โ€” issue to merged + +```mermaid +flowchart LR + A["๐Ÿ“‹ Pick the top
'Ready' issue
on the milestone board"] --> B["๐ŸŒฑ branch
feat/XXX-nn-slug"] + B --> C["๐Ÿ”จ code + tests
mvn verify ยท npm test
flutter analyze && flutter test"] + C --> D["โฌ†๏ธ push โ†’ PR on Gitea
template + screenshots"] + D --> E{"๐Ÿ‘€ PM review
โ‰ค 24h"} + E -->|"changes requested"| C + E -->|"approved"| F["๐Ÿ”€ squash merge
โ†’ main"] + F --> G["๐Ÿ” everyone:
git pull --rebase"] + G --> A + + classDef gate fill:#fdecea,stroke:#c0392b; + class E gate; +``` + +While a PR waits for review: **start the next Ready issue** โ€” never idle on a blocked PR. + +--- + +## 5. Dev vs production (so nobody confuses the two) + +| | Dev (your machine) | Production (later) | +|---|---|---| +| API config | `application-dev.yml` (safe defaults) | `application-prod.yml` โ€” **everything from env vars, fail-fast** | +| Database | docker Postgres, disposable (`down -v`) | managed PostgreSQL, backed up | +| Emails | Mailpit (nothing leaves the machine) | real SMTP (`MAIL_*` env) | +| Files | docker MinIO | S3-compatible storage | +| Secrets | dev-only values in dev yml | env vars only โ€” **never in git** | +| API docs | Swagger UI on | **off** | + +*Same code, same images, different profile โ€” that's the whole trick.* \ No newline at end of file