docs: add INDEX.md describing mozo repo relationships

2026-05-16 19:41:24 +02:00
parent 7364de2a45
commit efccbc2064
1 changed files with 83 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Mozo Project Index
+
+This file is the **canonical source of truth** for how the Mozo repositories relate to each other.
+When in doubt about cross-repo conventions, contracts, or terminology, the notes here win.
+
+## Repositories
+
+| Repo                  | Role                       | Stack                | Notes                                              |
+|-----------------------|----------------------------|----------------------|----------------------------------------------------|
+| **mozo-backend**      | Server / API (this repo)   | Ruby on Rails + CouchDB | Main repo. Authoritative data model + API. Owns this INDEX. |
+| **mozo-user**         | End-user client app        | Ember.js (client-side) | Customer-facing app, consumes the backend API.    |
+| **mozo-supplier**     | Supplier client app        | Ember.js (client-side) | Supplier-facing app, consumes the backend API.    |
+| **mozo-employee** *(planned/related)* | Employee client app | Ember.js (client-side) | Internal-staff app, consumes the backend API.    |
+
+All client apps speak HTTP(S) to **mozo-backend**. The backend is the single
+producer of canonical data; clients are presentation/UX layers around the
+same API surface, scoped to their respective user roles.
+
+```
+                       ┌────────────────────────────────────────────┐
+                       │              mozo-backend                  │
+                       │   Rails API · CouchDB · auth · domain      │
+                       │           (single source of truth)         │
+                       └───────────────▲────────────▲───────────────┘
+                                       │            │
+              ┌────────────────────────┘            └────────────────────────┐
+              │ HTTPS / JSON                          HTTPS / JSON           │
+              │                                                              │
+   ┌──────────┴──────────┐   ┌──────────────────────┐   ┌────────────────────┴┐
+   │     mozo-user       │   │   mozo-employee      │   │   mozo-supplier     │
+   │  Ember client app   │   │  Ember client app    │   │  Ember client app   │
+   │  (end customers)    │   │  (internal staff)    │   │  (suppliers)        │
+   └─────────────────────┘   └──────────────────────┘   └─────────────────────┘
+```
+
+## Source of truth rules
+
+- **Domain model / data model:** defined in `mozo-backend` (`app/models/`, `db/`, `doc/`).
+  Client apps must follow what the backend exposes; if a client needs new
+  data, it lands in the backend first.
+- **API contracts:** the backend's controllers + serializers are authoritative.
+  Client repos should not invent endpoints or payload shapes that don't exist
+  in the backend.
+- **Terminology / business rules:** documented in this repo (`doc/`, `wip.md`,
+  ADRs, this INDEX.md). If a client repo has a conflicting note, the
+  backend's version wins until it's reconciled here.
+- **Auth / sessions:** issued and validated by the backend; clients only
+  consume tokens/cookies, they don't define the rules.
+- **Cross-cutting decisions** (naming, statuses, lifecycle of entities,
+  deployment flow) belong in this INDEX or in `doc/decisions/` in this repo.
+
+## Client repos (Ember apps) — shared characteristics
+
+- Bootstrapped with Ember CLI (`.ember-cli`, `ember-cli-build.js`,
+  `testem.js`, `template-lintrc`, `eslint`).
+- Each one is a **separate Ember app** targeting a specific audience
+  (user / supplier / employee), not a monorepo of routes.
+- Each app talks to the backend over HTTPS (see backend `config/`,
+  `expose.sh`, SSL notes in `README.md`).
+- Build/deploy is per-client via `deploy.sh` in each client repo; the
+  backend handles its own deploy via Capistrano (`Capfile`,
+  `config/deploy*.rb`).
+
+## When you don't know which repo a question belongs in
+
+Ask in this order:
+
+1. Is it about **data, validation, business rules, or the API**? → `mozo-backend`.
+2. Is it about **what an end customer sees / does**? → `mozo-user`.
+3. Is it about **what a supplier sees / does**? → `mozo-supplier`.
+4. Is it about **internal staff tooling / dashboards**? → `mozo-employee`.
+5. Still unsure? → default to `mozo-backend` and document the answer here.
+
+## Maintenance
+
+Update this file whenever:
+
+- A new client app or service repo joins the Mozo project.
+- A cross-repo convention changes (auth flow, deploy flow, shared naming).
+- A repo's role or scope materially shifts.
+
+Keep it short. Detailed design lives in `doc/` and `doc/decisions/`; this file
+is a map, not a manual.