# Yumi — Architecture

This describes how the consolidated pieces fit together today (the MMD Cowork stack + LLM
router + Hindsight) and what each surface needs to run. It mirrors the source-of-truth doc at
`services/mmd-cowork-core/docs/COWORK_ARCHITECTURE.md`.

## Big picture

```
                ┌──────────────────────── surfaces ────────────────────────┐
 desktop        │ web / PWA        M365 packaging     Office add-in         │
 (Electron,     │ mmd-cowork-      mmd-cowork-m365    mmd-cowork-office     │
  SQLite)       │ mobile  ◄── also hosts /api/conversations (shared API)   │
 open-cowork-mmd└───────────────────────────┬──────────────────────────────┘
                  shared engine: @mmd/cowork-core   (conversation store, auth, agent tools,
                  shared config: @mmd/cowork-config (MCP servers, skills, surfaces, cred refs)
                                             │
        ┌────────────────────────────────────┼────────────────────────────────────┐
        ▼                                    ▼                                    ▼
  LLM router (LiteLLM)              Hindsight memory              MCP connectors
  services/mmd-llm-gateway          services/hindsight            (M365 Graph, FlowMaster,
  llm.baobab-ts.com                 durable memory + banks        SAP, …) via @mmd/cowork-config
        │                                    │
        ▼                                    ▼
  Z.ai GLM-5.2 (Anthropic           per-user / per-org banks
  dialect); claude-* aliases        (canonical example: bank `mmd`)
```

## Shared pillars

1. **Hindsight (memory).** Durable agent memory, *not* chat-transcript storage. Use it for
   facts, decisions, project learnings, summaries, guidance. Project-aware calls carry project
   tags/context. The MMD deployment is the reference (bank `mmd`).
2. **Static configuration (`@mmd/cowork-config`).** Single source for MCP server definitions +
   allowlists, skill bundles, surface metadata, design metadata, and credential references.
   Surfaces consume it; do not duplicate connector config per flavor.
3. **Shared conversations API.** `mmd-cowork-mobile` hosts `/api/conversations`; desktop and
   other surfaces sync projects/chats through it (desktop uses local SQLite as a cache). This is
   the seam Yumi will exploit so desktop + web + mobile **share memory and sessions**.

## LLM router (`services/mmd-llm-gateway`)

LiteLLM proxy, config-driven (`config/config.yaml`):
- Exposes one OpenAI-compatible and one Anthropic-compatible endpoint.
- Currently routes everything to **Z.ai GLM-5.2** (`api.z.ai/api/anthropic`), with aliases
  `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7` so existing Anthropic-style clients
  work unchanged.
- Provides virtual keys, per-key budgets, spend/token metering (Postgres), routing/fallback/
  retry/caching, and provider-key encryption at rest — the foundation for subscription billing.
- Add providers by appending `model_list` entries that read keys from env (`os.environ/...`);
  never inline keys in the config.

## Running locally

- **LLM router:** `cd services/mmd-llm-gateway && litellm --config config/config.yaml --port 4000`
  (requires `ZAI_API_KEY` and, for keys/budgets, Postgres + master/salt env). Validate the config
  before assuming the gateway is up.
- **Memory:** Hindsight ships Docker images and compose files under
  `services/hindsight/src/docker/` (`docker/` standalone + `docker/docker-compose/`). Start there
  for a local bank. Note `src/.env` / `src/.sesskey` are local secrets.
- **Surfaces:** each needs SSO + its external connectors to fully function. The web/PWA host also
  needs the connectors and Hindsight endpoint configured. See `config/sso/README.md`.

## Honest current-state caveats

- The cross-app backbone exists but is **not fully rolled out across every flavor** (per the
  source architecture doc, 2026-06-18). Verify a specific flavor's wiring before claiming it works.
- Surfaces currently authenticate via the **MMD Entra** app registration. Yumi's own
  Google/Apple/Microsoft SSO is **not yet registered**.
- This workspace is a faithful copy, not a deployable product yet — running anything live still
  points at the existing baobab/MMD infrastructure unless reconfigured.