How mikeonbreeze/cc-crossbeam works
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: sandbox.ts Sandbox bridge · flows Flows · src Express API · frontend Next.js app
Components 19
Frontend
Next.js browser app and API routes.
- Next.js app · Dashboard, auth, project pages, and persona-based views.
frontend - API routes · Frontend endpoints for extract, generate, project loading, and reset flows.
frontend/app/api - Live updates · Supabase auth, storage access, and realtime subscriptions for progress streams.
frontend/lib/supabase - Persona UI · Contractor and city dashboards, progress views, and result rendering.
frontend/components
Orchestrator
Express server that starts workflows and sandbox jobs.
- Express API · Cloud Run service exposing workflow entrypoints and coordinating runs.
server/src - Extract flow · Handles document extraction from plan PDFs and corrections letters.
server/src/routes/extract.ts - Generate flow · Triggers full resubmission-package generation and checklist-style outputs.
server/src/routes/generate.ts - Sandbox 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 · State-level ADU law, compliance, zoning, and permit rules.
server/skills/california-adu - City research · Municipal code lookup and city-specific ADU requirements.
server/skills/adu-city-research - Corrections · Interprets city corrections and maps them to responses and scope changes.
server/skills/adu-corrections-flow - Doc tools · 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 · TypeScript definitions for corrections analysis, response generation, and plan review.
agents-crossbeam/src/flows - Smoke tests · Layered validation from skill invocation checks to full pipeline scenarios.
agents-crossbeam/src/tests
State Layer
Supabase-backed persistence and realtime updates.
- Projects DB · Stores projects, runs, artifacts, and workflow state.
frontend/types/database.ts - File storage · Holds uploaded plans, letters, and generated documents.
- Realtime stream · Pushes run progress and agent messages to the browser.
Connections 22
- 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.