Update System Overview
1 parent
69337574eb
commit
0415cebde1
1 file changed
+179
-1
+179
-1
@@ -1 +1,179 @@
|
||||
Welcome to the Wiki.
|
||||
# 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<br/>backlog · reviews · decisions<br/>owns openapi.yaml"]
|
||||
DEVS["3 devs<br/>one per repo"]
|
||||
end
|
||||
|
||||
subgraph GITEA["🗄️ Gitea — ORIGIN (the only shared server)"]
|
||||
direction LR
|
||||
RAPI["trizagenda-api<br/>code · issues · board"]
|
||||
RWEB["trizagenda-web<br/>code · issues · board"]
|
||||
RMOB["trizagenda-mobile<br/>code · issues · board"]
|
||||
RTEAM["trizagenda-team<br/>this wiki · shared docs"]
|
||||
end
|
||||
|
||||
subgraph MACHINE["💻 Each dev machine (identical, self-sufficient)"]
|
||||
direction LR
|
||||
CLONES["local clones<br/>feature branches"]
|
||||
RUNTIME["local runtime<br/>API + clients + docker services<br/>(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<br/>React 19 · Vite · :5173<br/>session = httpOnly refresh cookie"]
|
||||
MOB["📱 trizagenda-mobile<br/>Flutter · emulator<br/>session = X-Refresh-Token header"]
|
||||
end
|
||||
|
||||
subgraph CONTRACT["📜 THE contract"]
|
||||
SPEC["openapi.yaml v1.2.1<br/>single source of truth<br/>(copy in each repo)"]
|
||||
PRISM["Prism mock · :4010<br/>fake API serving the spec"]
|
||||
end
|
||||
|
||||
subgraph APISRV["⚙️ trizagenda-api — Spring Boot · :8080/api/v1"]
|
||||
REST["REST JSON<br/>JWT Bearer 15 min<br/>+ rotating refresh tokens"]
|
||||
STOMP["WebSocket / STOMP<br/>(M4 — topic contract = spec candidate)"]
|
||||
end
|
||||
|
||||
subgraph COMPOSE["🐳 docker compose up -d (in trizagenda-api/)"]
|
||||
PG[("PostgreSQL 16 · :5432<br/>THE database — schema owned by Flyway")]
|
||||
REDIS[("Redis 7 · :6379<br/>rate-limit & cache backend (M6)")]
|
||||
MINIO[("MinIO · :9000 / UI :9001<br/>S3 files — avatars & attachments")]
|
||||
MAILPIT["Mailpit · SMTP :1025<br/>inbox UI → http://localhost:8025<br/>catches EVERY dev email (OTP reset)"]
|
||||
end
|
||||
|
||||
WEB -->|"HTTP JSON · cookie flow"| REST
|
||||
MOB -->|"HTTP JSON · 10.0.2.2:8080<br/>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<br/>'Ready' issue<br/>on the milestone board"] --> B["🌱 branch<br/>feat/XXX-nn-slug"]
|
||||
B --> C["🔨 code + tests<br/>mvn verify · npm test<br/>flutter analyze && flutter test"]
|
||||
C --> D["⬆️ push → PR on Gitea<br/>template + screenshots"]
|
||||
D --> E{"👀 PM review<br/>≤ 24h"}
|
||||
E -->|"changes requested"| C
|
||||
E -->|"approved"| F["🔀 squash merge<br/>→ main"]
|
||||
F --> G["🔁 everyone:<br/>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.*
|
||||
Reference in new issue
Block a user