# TBS Command Center — architecture review for Ella and Duarne

> This architecture report is based on Hermes's read-only inspection of the `tbs-command-center` repository at branch `_tmp-w1w3-base`, commit `4386157c633603933c3d03b207378d428571f068`, on 2026-09-08. Codex has not independently inspected the repository or source files.

**Review status: internal discussion draft for Ella and Duarne, before presentation to Dave.** Sole architecture source: [Hermes Markdown handoff](TBS-Command-Center-Architecture-Handoff-2026-09-08.md). Archify 2.17 supports supplied descriptions and was used to author the seven linked HTML diagrams without repository access. No application, configuration, deployment, credentials, or external services were modified. No environment-variable values are included.

## Evidence and checkout boundaries

**F — reported fact:** explicitly described by Hermes, not independently verified by Codex. **W — working-tree finding:** evidence touches a modified, deleted, or untracked file. **I — inference:** architectural interpretation. **U — unknown:** evidence is insufficient. These labels apply throughout this report and its diagrams. Unmarked repository citations below support F findings; a W qualifier takes precedence. File and line references are copied from the handoff, not newly inspected source. They are not links to verified commit contents.

**F, Git identity only:** Hermes reported branch `_tmp-w1w3-base`, HEAD `4386157c633603933c3d03b207378d428571f068`, and the last commit message `feat(clients): allow deleting a client card without deleting the linked contact`. This identifies the inspected base; it does not establish that all described code is committed, merged, or deployed.

**W:** the handoff's Git status lists modifications to `ROADMAP.md`, `components/Dashboard.tsx`, `firestore.indexes.json`, `firestore.rules`, `lib/define-route.ts`, `lib/ea/tools/__snapshots__/registry.test.ts.snap`, `lib/schema.ts`, `lib/tabs.ts`, and `vercel.json`; deletion of `components/tabs/ActivityLogTab.tsx`; and untracked `app/api/activity/`, `components/tabs/ActivityTab.tsx`, `lib/activity.ts`, `lib/activity.test.ts`, `.claude/`, and four planning/specification documents listed in the handoff. Thus gateway behavior, rules, schema, navigation, schedules, Activity, and roadmap status cannot safely be attributed wholesale to HEAD. Other F findings are still handoff observations, not a clean-commit audit.

## Purpose, users, and architecture

**F:** Command Center is an executive-assistant dashboard for Triumph Business Solutions, aggregating ClickUp tasks, priority email, calendar, VA questions, and Cowork activity (`README.md:1-5,9-21`). Dave/TBS is the initial audience. Membership code defines Lite, Creator, Professional, and custom Hermes access (`lib/membership-entitlements.ts:7-24,58-86`). **I:** it is evolving from a solo operations dashboard into a membership-based, multi-tenant workspace. **U:** production user population and isolation readiness; “solo today/multi-tenant ready” is a README claim (`README.md:23`).

| Component | Responsibility and evidence |
|---|---|
| Browser/PWA dashboard | Authenticated tabs, registry boot, entitlement filtering; `components/AuthProvider.tsx:43-63`; **W** `components/Dashboard.tsx:76-95,185-195`. |
| Next.js route layer | Server actions and integrations; **W** `defineRoute` centralizes auth, tenant resolution, and API-scope checks (`lib/define-route.ts:19-24,221-273`). |
| Firebase | Auth, Firestore client listeners where allowed, Admin SDK server access, and Storage (`lib/firebase-client.ts:1-6`; `lib/firebase-admin.ts:1-7,57-67`). **W:** document paths/rules summarized from `lib/schema.ts:1576-1801` and `firestore.rules:35-48`. |
| Domain modules | Today, Gmail, meetings/prep, registry/clients, projects, outreach, content, and QBO. Handoff section 5 cites corresponding `components/tabs/*`, `app/api/*`, and `lib/*` families. |
| Workstreams and local agents | Channels, messages, membership, department/profile metadata; local Project Harvey and Workstreams Hermes relays (`lib/workstreams/model.ts:86-115,172-209`; `package.json:13-19`; `lib/hermes/client.ts:75-115`). |
| LLM gateway | Tenant configuration, provider selection, spend reservation and reconciliation (`lib/llm/complete.ts:31-107`). |
| Activity workspace | **W:** agent roster/events outside the owner subtree, served by APIs; `lib/schema.ts:1398-1458,1699-1720`; `firestore.rules:39-48`; untracked Activity files. |

**I:** these are logical responsibilities within a Next.js application plus external/local services, not evidence of separately deployed microservices.

## Technology stack and integrations

**F, versions reported by Hermes:** Next.js 16.2.4 App Router, React 19.2.4, TypeScript, Tailwind CSS v4, Framer Motion, and lucide-react (`package.json:31-37,41-53`). Firebase client/Admin SDKs supply data and identity; Firebase Storage handles article/images and Vercel Blob handles Workstream attachments (`lib/firebase-admin.ts:57-67`; `package.json:25`; `lib/workstreams/model.ts:117-130`). Vercel hosting is documented (`README.md:75-78`); **W** cron configuration is cited at `vercel.json:1-92`. Vitest and Playwright are configured (`package.json:9-12,42,53`). These are source-packet versions, not live runtime measurements.

| Integration group | Reported surface; limits |
|---|---|
| Work and communications | ClickUp; Google Gmail/Calendar/Drive APIs; Granola meeting ingestion. Local gws/NotebookLM task posting is described in `README.md:80-140`. |
| Finance, CRM, membership | QBO OAuth/status/refresh/request routes; GHL; PayPal billing/signup/webhook routes. GHL relationship automation remains partly roadmap work. |
| Notifications and files | Resend, Web Push, Firebase Storage, Vercel Blob. |
| AI and local execution | OpenRouter, Anthropic, Max-plan worker adapter; local/tunneled Hermes `/v1/responses`. Tool-capable worker work remains open per roadmap. |

Evidence: handoff sections 3, 5, 7 and 13; `.env.example:42-130` **names only**, `lib/llm/complete.ts:23-75`, `lib/hermes/client.ts:75-101`. **U:** configured credentials, service health, live usage, and external permissions. Integration presence does not establish end-to-end readiness.

## Important data flows

1. **F/W — login and UI:** Host-based home/app split → Firebase auth state → registry/AppBootGate → permitted tabs (`app/page.tsx:5-12`; `components/AuthProvider.tsx:43-63`; **W** `components/Dashboard.tsx:76-95,185-195`). Browser actions send Firebase ID tokens; API verification uses Admin Auth (`lib/task-auth.ts:45-58`).
2. **F/W — automation ingest:** a task presents `X-Task-Api-Key`, with supplied/default tenant resolution; server writes via Admin SDK; permitted browser listeners or API refreshes expose updates (`lib/task-auth.ts:26-42,65-86`; `lib/firebase-admin.ts:49-55`; `README.md:9-18`). **W** gateway modes and rules determine applicable paths. Cron uses its own route-auth mode; it should not be assumed to share task-key auth.
3. **F/W — permissions:** browser users can resolve to an owner tenant through registry `ownerUid`; membership API scopes and configured seat scopes gate access. Browser-only routes reject task-key callers (**W** `lib/define-route.ts:63-75,134-193,252-267`). Machine bearer tokens are hashed, indexed, and checked against canonical tenant tokens for scope/revocation (`lib/content-engine-auth.ts:60-87`); **W** machine mode may allow configured legacy fallback (`lib/define-route.ts:82-107`).
4. **F — Workstream agent:** mention → stored message/queue → local relay claim → profile/department-directed Hermes call → stored response/update → dashboard readback (handoff section 13; `lib/workstreams/model.ts:86-115,132-155,172-209`; `lib/hermes/client.ts:75-101`). **U:** queue leasing, retries, deduplication, supervision, and exact readback transport. **W:** rules warn against adding client `onSnapshot` to Workstreams without scoped server reads or a rules rewrite (`firestore.rules:22-34`).
5. **F — LLM/spend:** `complete(rawReq)` resolves tenant configuration and provider chain → reserves spend before dispatch → calls selected adapters → reconciles usage/cost → returns result (`lib/llm/complete.ts:31-75,93-104`). Provider selection depends on tools/model/configuration; this is not an assertion that all providers execute. **U:** failure/refund, concurrent reservation, and fallback accounting behavior.
6. **F/W — scheduled work:** documented Vercel crons invoke meetings/prep, Dave OS maintenance, ClickUp/Rizle, pruning, Harvey, QBO, content notifications, Activity sweep, contacts refresh, and scheduled sends (**W** `vercel.json:1-92`). Exact cron expressions and production activation are not supplied. Local relays are separate dependencies, not demonstrated Vercel-hosted workers.

## Data model and functionality status

**F/W:** Firestore is a document model. Most records sit under `users/{uid}`; Workstream channels contain messages, which may reference threads/parents. Registry account users can resolve to an owner tenant. Outreach requests can produce drafts with status and optional `senderSeatId`; canonical tenant API tokens have a top-level hash index. Activity actors have records/events under `activity_workspaces/{tenantUid}` (**W** `lib/schema.ts:1218-1458,1576-1757`; `lib/workstreams/model.ts:86-115,172-209`; `lib/registry-types.ts:6-104`; handoff section 13). LLM keys are encrypted under `users/{uid}/system/llmKey` (`lib/openrouter/provisioning.ts:90-106,132-137`).

The logical ERD uses repeated tenant references for readability. It does not claim SQL foreign keys, mandatory relationships, cascade semantics, or unspecified cardinalities. Tenant-owned content includes posts/insights/articles; meetings have followups/preps and associated locks/cache; clients can link to Workstreams, tasks, timeline, vault context, QBO companies and finance state (handoff sections 6 and 13). Exact field completeness and deletion behavior remain unknown.

| Status | Reported scope |
|---|---|
| Implemented in inspected material | Auth/home split, Today, Gmail/drafting, meetings/prep, registry/clients, content, LLM gateway/spend, and QBO integration surface. Handoff section 5 supplies module paths. “Implemented” is not test or deployment certification. |
| Partial / evolving | Projects/Harvey, native Workstreams, outreach launch, and Vault/RAG. Activity is an explicit **W** addition. README calls `/api/vault/query` a Phase 1 stub while graph/vault modules exist (`README.md:142-145`; `lib/graphify/*`). |
| Roadmap claims, all **W** | Outreach W1-W3 “shipped/live”; W6 next; W4-W5/W8/W10/rest of W9 not built. LLM layers A/B and spend substantially shipped, tool-capable worker open. Relationship Contract slice 1 shipped; GHL pipelines/advanceStage/engine use open. Harvey draft staleness/cross-thread accuracy/task-panel HTTP 500 remain open/deferred. Workspace scope needs Dave; membership reconciliation remains (`ROADMAP.md:116-125`). |
| Roadmap only, **W** | Two-mode AI execution routing #36: documentation/roadmap, no registry/router code per the top entry (`ROADMAP.md:1-3,133`). This future router is not depicted as implemented. |

## Architectural/security risks

- **F/W, high-priority verification:** owner-subtree catch-all rules permit broad owner client access, including collections such as token hashes; Hermes quotes the rule comments' need for stricter untrusted multi-tenant isolation (`firestore.rules:8-20`). This is not proof of cross-tenant exploitation. Admin SDK bypasses client rules, so server tenant and seat checks require separate assurance (`firestore.rules:1-4,22-33`; `lib/define-route.ts:252-267`).
- **I:** shared legacy task authentication, caller/default tenant selection, and optional machine fallback increase the importance of explicit principal-to-tenant binding. Review each route's actual controls before wider access (`lib/task-auth.ts:26-42,65-86`; **W** `lib/define-route.ts:82-107`).
- **I:** a local/tunneled Hermes dependency introduces availability and private-agent access boundaries that the cloud app alone cannot establish. Verify profile authorization, relay recovery and result attribution (`lib/hermes/client.ts:75-115`; `lib/hermes/profile-routing.ts`, handoff section 13).
- **I:** sends, financial integrations and AI spend require failure-path/idempotency checks before reliability claims. The handoff does not demonstrate duplicate suppression, rollback, or budget concurrency guarantees. This is a verification task, not a confirmed defect.
- **F/U:** 327 test/spec files were inventoried, but Hermes ran no tests (handoff section 11). Codex ran artifact checks only. No application test pass, security audit, deployment health, or production environment correctness is claimed. Firebase production guards are described (`lib/firebase-admin.ts:17-41`; `lib/firebase-client.ts:43-51`), not exercised.

## Verification Gaps

| Gap | What remains unknown | Potential next task, not executed |
|---|---|---|
| Dirty checkout vs clean production branch | Which findings exist in clean code and in production; especially rules, gateway, schema, cron, Activity, roadmap. | Have an authorized reviewer compare the named HEAD and dirty diff with an explicitly identified clean production revision. Preserve separate receipts. |
| Current PR/deployment status | Hermes did not fetch GitHub PR status; deployment revision and active environment are unverified. | Verify named PRs and deployment metadata read-only, including revision and cron activation; disclose no secret values. |
| Firestore multi-tenant isolation | Owner/sub-user/machine isolation across client and Admin SDK paths; private Workstreams/Activity exposure. | Build a principal/tenant/seat access matrix and targeted deny tests in an isolated environment, using clean rules and gateway source. |
| Vault/RAG readiness | Stub versus usable indexed retrieval; graph loaders do not prove retrieval quality or authorization. | Inspect `/api/vault/query` handlers/loaders; establish corpus/index readiness and tenant-scoped retrieval tests in a separate review. |
| Route-level analysis gaps | Inventory parsing covers names/methods/auth hints, not every handler. “custom/none found” does not mean public/unauthenticated. | Inspect custom auth/callback/webhook/upload/Hermes platform routes and consequential send/approval/admin routes. Verify methods, principal binding, ownership, scopes, payload validation and side effects. |
| Agent and spend failure paths | Claim/retry semantics, agent scope, provider fallback costs and reservation recovery. | Trace representative failure/concurrency cases with source and isolated tests before any operational claims. |

Route evidence examples already in the handoff: `app/api/blob/upload/route.ts:12`, `app/api/hermes/platform/messages/route.ts:9`, `app/api/auth/google/callback/route.ts:5`, `app/api/gmail/send/route.ts:8`, and `app/api/actions/suggestions/[id]/approve/route.ts:18`. Some approval routes are inventoried as `any`; do not generalize browser-only auth to every approval endpoint. Exact supplemental handler checks are unknown.

## What Ella learned / Recommended next steps

For review with Duarne: the handoff shows an existing operations application with meaningful AI, workflow, and membership capabilities. The main uncertainty is which observed capabilities and protections belong to the clean, deployed system. Activity and the future execution router must not be presented as established production features.

1. Agree with Duarne on the intended audience, current product boundary, and which clean revision should anchor a Dave-facing report.
2. Prioritize provenance/deployment verification and tenant isolation over expanding feature claims. Assign reviewers and acceptance evidence for the gap table.
3. Decide whether Vault retrieval, Workstream/private-agent access, or outreach/LLM reliability is the next focused source review, based on the next user-facing release.
4. Present Dave only the agreed findings with F/W/I/U distinctions intact. Keep roadmap claims and proposed tasks separate from confirmed delivery. No task here constitutes an approved implementation or deployment plan.

## Diagram artifacts and validation

All seven standalone HTML diagrams use Archify's architecture renderer; the flow views are directional logical flow maps, not exact protocol traces. The ERD is a document-relationship projection. Grouped components and selected edges keep the diagrams readable; the detailed report above records additional interactions and caveats.

1. [System context](TBS-01-system-context.html)
2. [Application/container architecture](TBS-02-application.html)
3. [Data model / logical ERD](TBS-03-data-model.html)
4. [Authentication and permissions flow](TBS-04-auth.html)
5. [Workstream → Hermes agent flow](TBS-05-workstream-hermes.html)
6. [LLM / spend-governor flow](TBS-06-llm-spend.html)
7. [Deployment and scheduled jobs](TBS-07-deployment-jobs.html)

See [artifact receipts and review status](TBS-Artifact-Validation.md) for specification/artifact SHA-256 hashes, validation, browser evidence and perceptual review status. These checks assess generated artifacts, not repository correctness. All generated artifacts are in this folder.