# mikeonbreeze/cc-crossbeam architecture

> Architecture diagram of the GitHub repository mikeonbreeze/cc-crossbeam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikeonbreeze/cc-crossbeam
- Repository: https://github.com/mikeonbreeze/cc-crossbeam

## Overview

1. **What this repo is**
CrossBeam is an ADU permit-assistance system centered on long-running AI agents. Its main job is to ingest plan PDFs and city corrections letters, reason over California ADU rules plus city-specific codes, and output a resubmission package for contractors.

2. **Top-level architecture boundary**
The system is split into four runtime layers: the **Next.js frontend**, an **Express orchestrator server**, **Vercel Sandboxes** for agent execution, and **Supabase** for persistence and realtime updates. This separation exists because the agent runs are long-lived and need isolated filesystem access.

3. **Frontend subsystem**
`frontend/` is the user-facing app built with Next.js App Router, React, shadcn/ui, and Tailwind. It contains the dashboard, project detail pages, auth flows, and persona-based views for contractor/city experiences. It also exposes API routes that talk to the backend and subscribe to Supabase realtime updates.

4. **Frontend data access pattern**
The frontend does not do the heavy ADU analysis itself. It mostly:
- authenticates users through Supabase,
- creates/loads projects and runs,
- uploads or references source documents,
- renders live progress and final outputs from the database/realtime stream.

5. **Orchestrator/server subsystem**
`server/` is an Express service meant to run on Cloud Run. It owns the long-running workflow orchestration and bridges the frontend to the agent environment. The key routes are `/extract` and `/generate`, which trigger document extraction or full response-package generation.

6. **Sandbox execution boundary**
The server launches isolated **Vercel Sandbox** jobs for agent work. That sandbox is where Claude Opus 4.6 runs with filesystem access and the Agent SDK’s `claude_code`-style tooling. This is the critical execution boundary: the orchestration logic stays outside the sandbox, while document reading, reasoning, file generation, and agent tool use happen inside it.

7. **Primary workflow: corrections analysis**
The main pipeline starts with a contractor’s plan set PDF plus a city corrections letter. The agent:
- reads plan pages via vision,
- parses correction items,
- cross-references California state ADU law,
- researches city code and local requirements,
- asks clarifying questions,
- and produces outputs such as a corrections report, scope summary, and draft response letter.

8. **Secondary workflow: permit checklist generation**
A lighter flow accepts project basics like address, ADU type, size, and lot context. The agent researches city-specific rules and combines them with state-level constraints to produce a pre-submittal checklist and city-specific warnings.

9. **Knowledge layer: skills-first design**
Most domain logic lives in skills, not in application code. There are three important skill locations:
- `.claude/skills/` for local Claude Code usage,
- `server/skills/` for runtime-deployed skill assets,
- `adu-skill-development/skill/` as the development/source set.
These skills cover California ADU law, city research, corrections interpretation, document handling, and crossbeam operations. They are the repository’s main “knowledge boundary.”

10. **Document-processing subsystem**
The `document-skills/` content under the skill trees provides format-specific utilities for DOCX, PDF, PPTX, and XLSX work. This includes unpack/pack/validate helpers, PDF form extraction/filling, and OOXML schema references. These assets support the agent when it needs to inspect or generate office/document artifacts rather than just plain text.

11. **Agent configuration and test harness**
`agents-crossbeam/` contains TypeScript flow definitions, utilities, and layered smoke/integration tests. It is the agent-runtime implementation side of the system, separate from the end-user app. The tests progress from skill invocation checks to full pipeline scenarios, which makes this folder a good place to understand how the orchestration is expected to behave end-to-end.

12. **Persistence and live updates**
Supabase is the data backbone: Postgres stores projects, runs, and artifacts; Storage holds files; Realtime pushes run progress and agent messages to the browser. This is why the UI can show live status without polling, and why sandbox-generated outputs can be surfaced immediately.

13. **Reference data and fixtures**
`test-assets/` contains real-world PDF and JSON fixtures used to validate the workflows against actual permit data. `docs/`, `design-directions/`, and `progress.md` are supporting materials for product decisions, research, and hackathon development history rather than runtime components.

14. **Deployment boundary**
The frontend is deployed separately from the server. A GitHub Actions workflow exists for server deployment, and the server is containerized with a Dockerfile for Cloud Run. So the production shape is: browser-facing Next.js app on one edge, orchestration API on another, sandbox workers in the middle, and Supabase as the shared state layer.

Main entry points: [`server/src/services/sandbox.ts`](https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/services/sandbox.ts) (Sandbox bridge), [`agents-crossbeam/src/flows`](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/agents-crossbeam/src/flows) (Flows), [`server/src`](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/src) (Express API), [`frontend`](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend) (Next.js app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend"]
  node_node_browser_app["Next.js app<br/>web frontend"]
  node_node_frontend_routes["API routes<br/>route handlers"]
  node_node_frontend_realtime["Live updates<br/>realtime client"]
  node_node_frontend_ui["Persona UI<br/>ui components"]
end

subgraph group_group_server["Orchestrator"]
  node_node_server_api["Express API<br/>orchestrator server"]
  node_node_server_extract["Extract flow<br/>workflow route<br/>[extract.ts]"]
  node_node_server_generate["Generate flow<br/>workflow route<br/>[generate.ts]"]
  node_node_server_sandbox["Sandbox bridge<br/>execution bridge<br/>[sandbox.ts]"]
end

subgraph group_group_skills["Skills"]
  node_node_skill_california["California ADU<br/>policy skill"]
  node_node_skill_city["City research<br/>local code skill"]
  node_node_skill_corrections["Corrections<br/>analysis skill"]
  node_node_skill_docs["Doc tools<br/>document skillset<br/>[document-skills]"]
end

subgraph group_group_agents["Agent Runtime"]
  node_node_agent_flows["Flows"]
  node_node_agent_tests["Smoke tests<br/>integration harness"]
end

subgraph group_group_state["State Layer"]
  node_node_state_db[("Projects DB<br/>postgres data<br/>[database.ts]")]
  node_node_state_storage[("File storage<br/>object storage")]
  node_node_state_realtime["Realtime stream<br/>pubsub updates"]
end

subgraph group_group_support["Supporting Assets"]
  node_node_support_fixtures["Fixtures<br/>sample inputs"]
  node_node_support_deploy["Deploy"]
end

node_node_browser_app -->|"calls"| node_node_frontend_routes
node_node_browser_app -->|"subscribes"| node_node_frontend_realtime
node_node_browser_app -->|"renders"| node_node_frontend_ui
node_node_frontend_routes -->|"proxies to"| node_node_server_api
node_node_server_api -->|"serves"| node_node_server_extract
node_node_server_api -->|"serves"| node_node_server_generate
node_node_server_extract -->|"launches"| node_node_server_sandbox
node_node_server_generate -->|"launches"| node_node_server_sandbox
node_node_server_sandbox -->|"uses"| node_node_skill_california
node_node_server_sandbox -->|"uses"| node_node_skill_city
node_node_server_sandbox -->|"uses"| node_node_skill_corrections
node_node_server_sandbox -->|"uses"| node_node_skill_docs
node_node_server_sandbox -->|"writes"| node_node_state_db
node_node_server_sandbox -->|"stores"| node_node_state_storage
node_node_state_db -->|"publishes"| node_node_state_realtime
node_node_state_realtime -->|"feeds"| node_node_frontend_realtime
node_node_agent_flows -->|"encodes"| node_node_skill_california
node_node_agent_flows -->|"encodes"| node_node_skill_city
node_node_agent_flows -->|"encodes"| node_node_skill_corrections
node_node_agent_tests -->|"verifies"| node_node_agent_flows
node_node_agent_tests -->|"uses"| node_node_support_fixtures
node_node_support_deploy -->|"deploys"| node_node_server_api

click node_node_browser_app "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend"
click node_node_frontend_routes "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend/app/api"
click node_node_frontend_realtime "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend/lib/supabase"
click node_node_frontend_ui "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend/components"
click node_node_server_api "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/src"
click node_node_server_extract "https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/routes/extract.ts"
click node_node_server_generate "https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/routes/generate.ts"
click node_node_server_sandbox "https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/services/sandbox.ts"
click node_node_state_db "https://github.com/mikeonbreeze/cc-crossbeam/blob/main/frontend/types/database.ts"
click node_node_skill_california "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/skills/california-adu"
click node_node_skill_city "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/skills/adu-city-research"
click node_node_skill_corrections "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/skills/adu-corrections-flow"
click node_node_skill_docs "https://github.com/mikeonbreeze/cc-crossbeam/blob/main/.claude/skills/document-skills"
click node_node_agent_flows "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/agents-crossbeam/src/flows"
click node_node_agent_tests "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/agents-crossbeam/src/tests"
click node_node_support_fixtures "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/test-assets"
click node_node_support_deploy "https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_browser_app,node_node_frontend_routes,node_node_frontend_realtime,node_node_frontend_ui toneBlue
class node_node_server_api,node_node_server_extract,node_node_server_generate,node_node_server_sandbox toneAmber
class node_node_skill_california,node_node_skill_city,node_node_skill_corrections,node_node_skill_docs toneMint
class node_node_agent_flows,node_node_agent_tests toneRose
class node_node_state_db,node_node_state_storage,node_node_state_realtime toneIndigo
class node_node_support_fixtures,node_node_support_deploy toneTeal
```

## Components

### Frontend

Next.js browser app and API routes.

- [Next.js app](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend): web frontend · Dashboard, auth, project pages, and persona-based views. · `frontend`
- [API routes](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend/app/api): route handlers · Frontend endpoints for extract, generate, project loading, and reset flows. · `frontend/app/api`
- [Live updates](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend/lib/supabase): realtime client · Supabase auth, storage access, and realtime subscriptions for progress streams. · `frontend/lib/supabase`
- [Persona UI](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/frontend/components): ui components · Contractor and city dashboards, progress views, and result rendering. · `frontend/components`

### Orchestrator

Express server that starts workflows and sandbox jobs.

- [Express API](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/src): orchestrator server · Cloud Run service exposing workflow entrypoints and coordinating runs. · `server/src`
- [Extract flow](https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/routes/extract.ts): workflow route · Handles document extraction from plan PDFs and corrections letters. · `server/src/routes/extract.ts`
- [Generate flow](https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/routes/generate.ts): workflow route · Triggers full resubmission-package generation and checklist-style outputs. · `server/src/routes/generate.ts`
- [Sandbox bridge](https://github.com/mikeonbreeze/cc-crossbeam/blob/main/server/src/services/sandbox.ts): execution bridge · Launches isolated Vercel Sandbox jobs for long-lived agent work. · `server/src/services/sandbox.ts`

### Skills

Domain knowledge and document-processing skill trees used by agents.

- [California ADU](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/skills/california-adu): policy skill · State-level ADU law, compliance, zoning, and permit rules. · `server/skills/california-adu`
- [City research](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/skills/adu-city-research): local code skill · Municipal code lookup and city-specific ADU requirements. · `server/skills/adu-city-research`
- [Corrections](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/skills/adu-corrections-flow): analysis skill · Interprets city corrections and maps them to responses and scope changes. · `server/skills/adu-corrections-flow`
- [Doc tools](https://github.com/mikeonbreeze/cc-crossbeam/blob/main/.claude/skills/document-skills): document skillset · PDF, DOCX, PPTX, and XLSX handling, validation, and form operations. · `.claude/skills/document-skills`

### Agent Runtime

TypeScript flow definitions and harnesses for pipeline behavior.

- [Flows](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/agents-crossbeam/src/flows): agent workflows · TypeScript definitions for corrections analysis, response generation, and plan review. · `agents-crossbeam/src/flows`
- [Smoke tests](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/agents-crossbeam/src/tests): integration harness · Layered validation from skill invocation checks to full pipeline scenarios. · `agents-crossbeam/src/tests`

### State Layer

Supabase-backed persistence and realtime updates.

- [Projects DB](https://github.com/mikeonbreeze/cc-crossbeam/blob/main/frontend/types/database.ts): postgres data · Stores projects, runs, artifacts, and workflow state. · `frontend/types/database.ts`
- **File storage**: object storage · Holds uploaded plans, letters, and generated documents.
- **Realtime stream**: pubsub updates · Pushes run progress and agent messages to the browser.

### Supporting Assets

Docs, fixtures, and deployment artifacts.

- [Fixtures](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/test-assets): sample inputs · Real PDFs, manifests, and expected outputs used for workflow validation. · `test-assets`
- [Deploy](https://github.com/mikeonbreeze/cc-crossbeam/tree/main/server/Dockerfile): build/deploy · Dockerized server deployment and GitHub Actions release workflow. · `server/Dockerfile`

## Connections

- Next.js app → API routes: calls · UI actions submit extract, generate, and project requests.
- Next.js app → Live updates: subscribes · Screens consume realtime run progress and artifact updates.
- Next.js app → Persona UI: renders · Pages assemble dashboards, forms, and result views from reusable components.
- API routes → Express API: proxies to · Frontend API routes forward orchestration requests to the server.
- Express API → Extract flow: serves · Routes expose the extraction workflow entrypoint.
- Express API → Generate flow: serves · Routes expose the generation workflow entrypoint.
- Extract flow → Sandbox bridge: launches · Extraction work is executed inside isolated sandbox jobs.
- Generate flow → Sandbox bridge: launches · Full response-package generation runs in sandboxed agent jobs.
- Sandbox bridge → California ADU: uses · Sandbox agents rely on state ADU law and compliance knowledge.
- Sandbox bridge → City research: uses · Sandbox agents research city-specific codes and local rules.
- Sandbox bridge → Corrections: uses · Sandbox agents interpret corrections and derive responses.
- Sandbox bridge → Doc tools: uses · Sandbox agents read, validate, and generate office documents.
- Sandbox bridge → Projects DB: writes · Workflow state, artifacts, and run records are persisted.
- Sandbox bridge → File storage: stores · Uploaded inputs and generated files are stored as blobs.
- Projects DB → Realtime stream: publishes · Database-backed state changes drive realtime browser updates.
- Realtime stream → Live updates: feeds · Realtime stream updates the UI without polling.
- Flows → California ADU: encodes · Flow logic is guided by state law knowledge assets.
- Flows → City research: encodes · Flows incorporate city research and local rule lookup.
- Flows → Corrections: encodes · Flows define corrections analysis and response generation behavior.
- Smoke tests → Flows: verifies · Harness exercises the agent workflows end to end.
- Smoke tests → Fixtures: uses · Integration scenarios run against real permit data fixtures.
- Deploy → Express API: deploys · Server runtime is containerized and released separately.
