# 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.