# Multi-domain Command Dashboard Architecture

Use this when designing a single command-center dashboard over several sensitive or semi-independent systems (e.g. finance, health, media automation) that already have separate repositories/backends.

## Core pattern

Prefer **one frontend + one thin BFF/API gateway + separate domain backends**:

```text
Command Dashboard Frontend
        ↓
API Gateway / BFF: auth, module registry, aggregation, audit, redaction
        ↓
Domain adapters → separate Finance / Health / Media / System backends
```

Do **not** collapse sensitive domains into one super-database. Keep each domain's repo, database, secrets, jobs, audits, tests, and ownership separate. The dashboard owns UI state, sessions, module registry, gateway audit, feature flags, and non-sensitive cached status snapshots only.

## Context-loss mitigation

When the user worries that a main chat will lose the big-picture architecture, move the source of truth into the repo immediately:

- `docs/architecture.md` — target architecture and boundaries.
- `docs/security.md` — domain sensitivity, redaction, auth, no-secrets rules.
- `docs/decisions/*.md` — ADRs for durable architecture decisions.
- `docs/module-contracts/<domain>.md` — stable API contracts per module.
- GitHub Issues/Milestones with labels by module, phase, and risk.
- Contract tests so individual subsystems can evolve without breaking the dashboard.

This lets the user work independently on a subsystem without endangering the command dashboard, provided the module contract remains stable or is versioned deliberately.

## Recommended phased delivery

1. **Phase 0: Inventory and approval** — list repos, stacks, ports, APIs, data stores, sensitive boundaries, legacy dashboard URLs.
2. **Phase 1: Repo bootstrap** — frontend app, gateway app, docs, ADRs, `.env.example`, smoke tests.
3. **Phase 2: Dashboard shell** — JARVIS/HUD layout, module cards, legacy links, static/mock data.
4. **Phase 3: Read-only gateway integrations** — module status, reports, activity, failures as degraded states.
5. **Phase 4+: Native modules** — integrate the lowest-risk/highest-value module first, then sensitive modules with stricter gates.
6. **Approvals Center** — only after contracts exist: Preview → Confirm → Audit.
7. **Hardening** — auth, Tailscale/internal deployment, logs with redaction, backups, E2E tests.

## MVP scope

MVP should prove aggregation and navigation, not replace every existing dashboard:

- central overview
- module status cards
- activity timeline
- pending approvals panel
- reports panel
- links to legacy dashboards
- read-only adapters/stubs
- no sensitive writes

Explicit MVP non-goals:

- no automatic finance trades/bookings
- no health-risk decisions or raw health exposure
- no public publishing without approval
- no public deployment unless intentionally designed
- no shared sensitive database

## API contract primitives

Define shared primitives early:

- `ModuleStatus`: id, name, status, severity, updated_at, summary, metrics, links.
- `ActivityEvent`: timestamp, module, type, severity, title, artifact reference.
- `ApprovalItem`: module, title, risk, status, preview/confirm actions.
- `ReportLink`: module, title, kind, updated_at, URL/proxy ref, sensitivity.

Use adapters to translate each backend into these primitives. If a backend lacks APIs, adapters may initially read safe status files, check report existence, or expose static links — read-only only.

## Security rules

- Frontend never receives secrets.
- Gateway handles auth, redaction, and sensitive proxying.
- Sensitive domains get aggregated summaries first; raw data requires explicit protected views.
- All write actions require Preview → Confirm → Audit.
- Domain audit remains in the domain backend; gateway audit records what was triggered through the command dashboard.
- Prefer local/Tailscale-only deployment for the first production iteration.

## Repo shape example

```text
Jarvis/
├── apps/
│   ├── dashboard/
│   └── api-gateway/
├── packages/
│   ├── contracts/
│   ├── ui/
│   └── theme/
├── docs/
│   ├── architecture.md
│   ├── security.md
│   ├── decisions/
│   ├── module-contracts/
│   └── runbooks/
├── scripts/
└── tests/
```

## Developer-report deliverable checklist

For a user-facing approval concept, include:

- executive summary
- current-system inventory
- architecture diagram
- repo/work model
- MVP definition and non-goals
- module functionality by domain
- API contract sketches
- phased implementation plan
- security model
- testing strategy
- open questions and approval decision text