# JARVIS Command Dashboard — Architecture Overview

**Phase:** 2A architecture/contracts only  
**Status:** accepted baseline for future implementation  
**Sources:** `docs/inventory/*.md` from commit `9c00dc30967d6ae28f06b351124182366ed8f74b`

## Purpose

JARVIS Command Dashboard is the central local/Tailscale command surface over separate domain systems. It is a **Command Layer**, not the source of truth.

It aggregates safe status, summaries, links and future approval workflows from:

- `finance` — FinanceManager
- `health` — HealthManager
- `autoshorts` — AutoShorts system
- `system` — JARVIS/Hermes system status

It does **not** replace those systems, migrate their data, or merge their databases. If one domain changes internally, the JARVIS Dashboard remains stable as long as the domain contract remains stable or is deliberately versioned.

## High-level architecture

```mermaid
flowchart TD
    U[User on iPad/Desktop via Tailscale] --> F[JARVIS Dashboard Frontend]
    F --> G[JARVIS API Gateway / BFF]

    G --> MR[Module Registry]
    G --> R[Redaction Layer]
    G --> A[Gateway Audit Metadata]
    G --> C[Contract Validation]

    G --> FA[Finance Adapter]
    G --> HA[Health Summary Adapter]
    G --> AA[AutoShorts Adapter]
    G --> SA[System Adapter]

    FA --> FM[FinanceManager API / Runtime]
    HA --> HM[HealthManager Summary API or Allowlisted Metadata Bridge]
    AA --> AS[AutoShorts API]
    SA --> JS[JARVIS/Hermes Local Runtime]

    FM -. separate DB/secrets/audit .-> FMD[(Finance Runtime DB)]
    HM -. separate DB/reports/backups .-> HMD[(Health Runtime DB)]
    AS -. separate media/runtime .-> ASD[(AutoShorts Runtime)]
```

Text form:

```text
Vue/Vite/TypeScript Frontend
        ↓
FastAPI Gateway / BFF
        ↓
Adapter boundary per module
        ↓
Existing domain systems remain separate
```

## Frontend architecture

Planned stack for later implementation:

- Vue 3
- Vite
- TypeScript
- PrimeVue
- Tailwind
- Pinia only if needed for UI state

Phase 2A creates **no frontend code**.

### iPad-first MVP constraint

The homepage must remain an executive cockpit, not a landfill with gradients:

- maximum 5 global Attention Items
- maximum 4 module cards
- maximum 3 KPIs per module card
- no raw tables on the global overview
- no Health/Finance raw data on the global overview
- touch-friendly spacing and actions for iPad

## Gateway architecture

Planned stack for later implementation:

- FastAPI
- Pydantic models generated from the documented contracts
- HTTPX for domain API calls
- SQLite only for non-sensitive dashboard metadata, if needed

Allowed gateway-owned data:

- module registry cache
- non-sensitive status snapshots
- feature flags
- UI preferences
- session metadata
- future gateway audit metadata

Forbidden gateway-owned data:

- Health raw values
- Finance exact values on global overview
- SQLite production DB copies
- exports/reports/PDFs
- secrets/tokens/OAuth files
- domain runtime files

## Adapter principle

Each domain is integrated through a narrow adapter. The adapter translates a domain-specific source into the shared `ModuleSnapshot` contract.

Adapter rules:

1. Adapter input can be API, sqlite summary, filesystem metadata, static config, or mock.
2. Adapter output must match the shared contract.
3. Adapter output must pass forbidden-field validation.
4. Adapter failures become `degraded` or `offline`, never stack traces in the frontend.
5. Adapter code may not mutate domain state in MVP.

## Module Registry

The Module Registry declares:

- module id and title
- sensitivity
- source type
- base URL or runtime config key
- legacy link config key
- contract version
- display policy
- disabled actions

Legacy dashboards are links from the registry. They are not embedded.

## Data flow

1. Frontend requests `GET /overview` from Gateway.
2. Gateway loads module registry.
3. Gateway queries each read-only adapter or returns cached/degraded snapshot.
4. Adapter normalizes data into `ModuleSnapshot`.
5. Redaction layer removes forbidden fields and enforces display policies.
6. Gateway composes `OverviewResponse` with max 5 Attention Items.
7. Frontend renders module cards and attention items.

## Error / degraded / offline model

- `ok`: source reachable and fresh.
- `attention`: source reachable but user action/awareness is needed.
- `degraded`: source reachable but stale, partial, or sanitized fallback is being used.
- `offline`: source unavailable or timed out.

Errors must be redacted. Internal exception strings, filesystem paths, DB paths and URLs with secrets never reach the frontend.

## Why no monolith

A monolith would couple unrelated risk domains: finance, health, media automation and system operations. It would increase blast radius, make reviews harder and invite accidental data mixing. Splendid, if one enjoys regulatory migraines. We do not.

## Why no super database

There is no shared domain schema. Each system remains source of truth for its own data:

- FinanceManager owns finance runtime and audit.
- HealthManager owns health runtime and backups.
- AutoShorts owns production/media state.
- JARVIS/Hermes owns system runtime and cron state.

JARVIS may store only non-sensitive dashboard metadata.

## Why legacy links instead of iframes

Legacy dashboards may expose sensitive views, browser storage assumptions, route-level actions and inconsistent auth boundaries. Links are explicit navigation. iframes hide security context and confuse UX. Embedding requires a later written technical justification and security review.

## Current pre-integration blocker

FinanceManager local working copy was observed to be 3 commits ahead of remote during inventory. Before Finance adapter implementation, those commits must be pushed, discarded, or separately reviewed. No FinanceManager files are changed in this phase.