84 lines
5.0 KiB
Markdown
84 lines
5.0 KiB
Markdown
# 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.
|