# System Architecture Overview

**Last updated:** 2026-05-19
**Status:** Living doc. Update as new users / endpoints / KV keys are added.

> **Visual companion:** [system-overview.html](./system-overview.html) — 5-layer diagram (domains → projects → sections → roles → data) as a static SVG reference.

This is the high-level view of who connects to what. For the file-level view, see [`/personal/status-tracker/substrate-map.html`](/personal/status-tracker/substrate-map.html). For the visual 5-layer architecture diagram, see [`system-overview.html`](./system-overview.html) (newly added 2026-05-19).

## Users + their hubs

| User | Hub URL | What lives there |
|---|---|---|
| **Sam** (admin) | `/` (root) | Project tiles · CC activity strip · From-Win strip · quick-capture · install panel |
| **Sam** (deep ops) | `/personal/status-tracker/dashboard.html` | Week strip · issues · CC activity tile · quick-add · ripening · thoughts · health |
| **CeCe** (partner) | `/our/` | Greeting · weather · today · this week · linked-task tiles (boarding, coach email) · Pittsburgh trip card · capture row |
| **Win** (son, ~7) | `/win/` | 11 tiles (ideas/printer/sports/cards/RCs/games/messages/school/help/trip/schedule) · theme switcher · capture row |
| **Jon Aceves** (first customer) | `/jon/` | Standalone customer hub — property, jobs, billing link, survey + price reveal, bets opt-in, message, request feature, contact |
| **Future customers** | `/customer/?id={customer-id}` | Generalized pattern (same tiles as /jon/) |

## Data layer (Cloudflare KV)

**Namespace:** `OUR_HUB_DATA` (binding `env.OUR_KV` on Pages Functions)

**Endpoints:**
- `/our/data?key={k}` — GET / PUT / POST / DELETE — main read/write
- `/handoff/post` — write to `cc-prompt-{key}` namespace (captures + CC prompts)
- `/handoff/get?key={k}` — read from `cc-prompt-{key}` namespace
- `/handoff/get?list=1` — index of recent cc-prompt-* keys
- `/handoff/quick-paste.html` — Sam's planning-chat → CC bridge UI

**KV key inventory (canonical):**

| Pattern | Purpose | Writer | Reader |
|---|---|---|---|
| `calendar` | Sam+CeCe shared calendar events | /our/calendar.html (SEED + migrations) | /our/ · /our/calendar · root hub · /win/my-schedule (filtered) |
| `lists` | /our/ lists (groceries, errands, remember, pgh-pack) | /our/lists.html | /our/lists.html |
| `task-boarding-decision` | Linked-task: Club Pet vs Megan | /our/lists.html | /our/lists.html · /our/ Fri AM tile |
| `task-coach-email-sent` | Linked-task: Win flag football coach email | (TBD — Sam marks done) | /our/ alert tile |
| `cc-activity-current` (under cc-prompt-) | CC's live activity feed | CC each session | Root hub strip · `/personal/status-tracker/dashboard.html` tile |
| `messages-from-win` | Win → Sam thread | CC merges from win-message-* captures | Root hub "From Win" strip |
| `sam-replies-to-win` | Sam → Win replies | Root hub reply form | `/win/message-dad.html` poll |
| `customer-messages-{customer}` | Customer ↔ Sam thread | /jon/message-sam · /customer/message-sam | /customer/admin · (future Sam-side surface) |
| `customer-requests-{customer}` | Customer feature requests | /jon/request-feature · /customer/request-feature | /customer/admin (future: CC creates issue) |
| `survey-response-{customer}-{job}` | Customer survey answers | /jon/survey · /customer/survey | /customer/admin |
| `survey-completed-{customer}-{job}` | Boolean gate for price reveal | survey on submit | job-review pages |
| `announcements` | Sam's announcements to customers | (TBD — Sam-side authoring) | /jon/whats-new · /customer/whats-new |
| `whats-new-read-{customer}` | Per-customer announcement read state | customer hub | customer hub |
| `invite-sent-{recipient}` | Last-sent timestamp per invite target | /invites/ | /invites/ |
| `win-ideas` | Win's ideas with ripeness | /win/ideas | /win/ideas |
| `win-sports` · `win-cards` · `win-games` · `win-rcs-state` · `win-tools-known` · `win-contributions` · `win-learned` · `win-homework` · `win-trip-pack` · `win-color-vote` · `win-color-vote-history` · `win-messages-sent` | Win's hub data | /win/* | /win/* |
| `thoughts-inbox` | Sam's thoughts inbox | quick-capture | dashboard thoughts panel |
| `ripening` | Sam's almost-ready ideas | /personal/status-tracker/ripening.html | dashboard ripening panel |
| `ripening-promote-queue` | Promote-to-issue queue | ripening.html | CC session-start step 5b |
| `print-status.json` (static) | Pirates/Phillies/chains production | Sam (commits) | /our/ · /win/printer · /personal/3d-printing/dashboard |

**Capture KV namespace (cc-prompt-{key} via /handoff/post):**

| Prefix | Action by CC on next session |
|---|---|
| `cc-prompt-queued-*` · `cc-prompt-urgent-*` | Sam-queued prompts → CC processes |
| `cc-activity-current` | Own write, skip |
| `issue-new-*` | Merge to issues.json with next id |
| `thoughts-new-*` | Merge to thoughts-inbox |
| `cal-new-*` | Merge to calendar with idempotent migration |
| `note-new-*` | Route per `for:` field |
| `win-message-*` | Append to messages-from-win |
| `win-color-vote-*` | Append to win-color-vote-history (canonical win-color-vote tracks current) |
| `win-rcs-status-*` · `win-rcs-note-*` · `win-tools-suggested-*` · `win-photo-*` | Win-side notifications to Sam |
| `customer-survey-*` | Append to surveys panel; flag rating ≤ 3 |
| `customer-message-*` | Append to messages-from-{customer} |
| `customer-feature-request-*` | Create issue with severity from importance |

## Authentication

| User | Method | Trust boundary |
|---|---|---|
| Sam | Implicit (owns the repo) | All routes |
| CeCe | None (Phase 1) — URL-as-key on `/our/` | Shared with Sam |
| Win | None (Phase 1) — URL-as-key on `/win/` | Kid-safe scope, no billing |
| Jon | None (Phase 1) — URL-as-key on `/jon/` | Phase 2 adds Firebase Auth |
| All customers (general) | Existing Firebase Auth on `/manage` for billing data | Customer-only auth |

**Trust boundary:** the substrate (this repo) is URL-keyed. Sensitive billing + customer details live in `/manage` app behind Firebase Auth. The substrate hubs link OUT to /manage for those. Phase 2 will move auth boundary into the substrate via Pages Functions middleware.

## Cross-hub data flow

```
                  ┌───────────────────────┐
                  │   Cloudflare KV       │
                  │   (OUR_HUB_DATA)      │
                  └──────────┬────────────┘
                             │
       ┌────────┬────────────┼──────────┬──────────────┐
       │        │            │          │              │
  ┌────▼───┐ ┌──▼───┐  ┌─────▼──┐ ┌─────▼────┐ ┌──────▼─────────┐
  │ Sam    │ │/our/ │  │ /win/  │ │  /jon/   │ │ /manage app    │
  │  /     │ │ +    │  │  +     │ │  +       │ │ (Firebase Auth)│
  │ cockpit│ │ KV   │  │  KV    │ │  KV      │ │  separate repo │
  └────────┘ └──────┘  └────────┘ └──────────┘ └────────────────┘

Bidirectional state (linked tasks):
  Sam ↔ CeCe — calendar, lists, boarding decision, coach email task
  Sam ↔ Win  — messages, RC car status, color votes, idea help-requests
  Sam ↔ Jon  — surveys, feature requests, messages, announcements
```

```mermaid
graph TD
  KV[("Cloudflare KV<br/>OUR_HUB_DATA")]:::data

  subgraph SamUser["Sam"]
    Root[Root Hub<br/>/]
    Cockpit[Cockpit<br/>/personal/status-tracker/dashboard.html]
  end

  subgraph CeCeUser["CeCe"]
    Our[/our/]
  end

  subgraph WinUser["Win"]
    Win[/win/]
  end

  subgraph JonUser["Jon"]
    Jon[/jon/]
    Customer[/customer/?id=jon-aceves<br/>generalized pattern]
  end

  Manage[Manage App<br/>Firebase Auth<br/>separate repo]:::external

  Root <--> KV
  Cockpit <--> KV
  Our <--> KV
  Win <--> KV
  Jon <--> KV
  Customer <--> KV

  Root -.billing link.-> Manage
  Jon  -.billing link.-> Manage
  Customer -.billing link.-> Manage

  classDef data fill:#FFB612,stroke:#101820,color:#101820;
  classDef external fill:#fafaf7,stroke:#666,color:#666,stroke-dasharray: 5 5;
```

## Linked-task pattern (key abstraction)

Some tiles on one hub bind to state another hub writes. Pattern:

1. KV key holds the canonical state (e.g., `task-boarding-decision`)
2. Writer surface (e.g., `/our/lists.html` Decisions panel) renders an editable UI
3. Reader surface (e.g., `/our/` Fri AM alert tile) polls the same key every 30 s and re-renders
4. Both surfaces poll on visibility-change so state binding feels instant when switching apps

Live examples:
- `task-boarding-decision` (CeCe picks on lists → Sam sees on /our/ home)
- `task-coach-email-sent` (Sam marks done → /our/ alert tile flips to ✓)
- `win-color-vote` (Win picks on /win/printer → Sam sees in /win/printer too)
- `messages-from-win` ↔ `sam-replies-to-win` (Win→Sam→Win round-trip)

This pattern generalizes for any future "Sam-Jon" or "Sam-CeCe" coordination need.

## Where to add new things

- **New customer:** create `/customer-data/{id}/config.json` + `job-{job}.json` files; share `/customer/?id={id}` URL via /invites/. For Jon-style standalone treatment, also create `/{id}/index.html` etc.
- **New /our/ shared concern:** add to `/our/calendar.html` SEED + MIGRATIONS or `/our/lists.html` IMPORTS array.
- **New Win tile:** new file at `/win/{name}.html` + tile entry in `/win/index.html` tile-grid.
- **New linked task:** new `task-{name}` KV key + writer UI + reader tile. Poll 30 s. Document in this file's KV table.
- **New CC capture flow:** new `*-new-*` prefix + entry in step 5c of [`/handoff-blocks/automation-rules.md`](/handoff-blocks/automation-rules.md).

## Related docs

- [`/handoff-blocks/automation-rules.md`](/handoff-blocks/automation-rules.md) — CC's per-session procedure + auto-resolve rules
- [`/handoff-blocks/customer-portal-flow.md`](/handoff-blocks/customer-portal-flow.md) — Jon's user-flow diagram
- [`/handoff-blocks/multi-user-setup-guide.md`](/handoff-blocks/multi-user-setup-guide.md) — CeCe + Win install session script
- [`/handoff-blocks/ai-coordination/working-with-sam.md`](/handoff-blocks/ai-coordination/working-with-sam.md) — Sam's operating manual
- [`/personal/status-tracker/substrate-map.html`](/personal/status-tracker/substrate-map.html) — File-level inventory (auto-generated)