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