# ryanshabaneh/shipyard architecture

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

- Interactive diagram: https://gitdiagram.com/ryanshabaneh/shipyard
- Repository: https://github.com/ryanshabaneh/shipyard

## Overview

1. **Overall shape**
   Shipyard is a two-tier TypeScript monorepo: a **Next.js frontend** in `frontend/` and an **Express + Socket.IO backend** in `server/`. The product is not just a UI; it is a workflow engine that scans a GitHub repo, streams analysis live, lets specialized AI agents propose code changes, and then supports commit/push from inside the app.

2. **Frontend boundary**
   The frontend is a **Next.js 14 App Router** app (`src/app`) with the usual split between route entrypoints (`page.tsx`, `layout.tsx`) and feature components. It owns the interactive experience: the 3D city, HUD overlays, repo selection/auth UI, per-building panels, and the chat/acceptance flow. It also contains the public assets for the city: many `.glb`/`.fbx` models, fonts, and icon packs.

3. **Scene and visualization layer**
   The main visual subsystem lives under `src/components/scene` and `src/components/layout`. This is where the “production readiness city” is rendered: buildings, island/terrain, clouds, camera, and different city variants like Vancouver or village views. These components are largely presentation/3D orchestration, separate from app state and backend communication.

4. **UI and interaction layer**
   Reusable HUD and modal components are under `src/components/ui`. They represent the control plane around the city: login overlays, repo/platform pickers, chat windows, progress indicators, building detail panels, task checklists, and acceptance dialogs. This layer is the primary bridge from visualization to backend actions.

5. **Frontend state and server communication**
   State is centralized through `src/store/useStore.ts`, with additional behavior in hooks such as `useAuth`, `useSocket`, `useScan`, `useBuildingFlow`, `useAgent`, and `useImplement`. The important architectural pattern is: **UI state lives in the browser store, while backend work is event-driven over Socket.IO and HTTP**. `SocketContext` wraps realtime connectivity so scan progress and agent updates can stream into the city view.

6. **Backend API and realtime transport**
   The backend exposes route modules in `src/routes` for the major workflow steps: auth, scan, chat, implement, verify, evaluate, export, accept/reject, push, and platform selection. This is the command surface of the system. Socket.IO is used for live updates so deterministic scans and AI progress can drive the frontend in real time rather than waiting for full request completion.

7. **Repo analysis pipeline**
   The scanner subsystem in `src/scanner` is the deterministic analysis engine. It clones the target repository, then runs analyzers for the eight production-readiness categories described in the README: tests, CI/CD, Docker, documentation, environment variables, security, logging, and deployment. Each analyzer is isolated in `src/scanner/analyzers`, which makes the readiness score and building growth reproducible and non-AI-dependent.

8. **AI agent subsystem**
   The `src/agents` area handles the specialist copilots that work on specific buildings/categories. The files suggest a layered design: shared base/context/client logic, a scanner-aware context, prompt format definitions, and specialized evaluators/analyzers. This subsystem is responsible for taking the current repo state, the scanner findings, and relevant source-file context to generate implementation guidance or code edits via Anthropic/Claude.

9. **Change application and safety boundaries**
   Proposed code changes are not applied directly by agents. The `src/changes` subsystem queues and exports changes, which separates **generation** from **application**. `src/sandbox` provides controlled execution for verification or code operations, while `src/routes/verify`, `evaluate`, `accept`, `reject`, and `export` indicate a guarded review loop before anything is committed or pushed.

10. **Session, auth, and repo access**
   `src/session/store.ts` and `src/routes/auth.ts` indicate server-side session persistence, while the README shows GitHub OAuth as the entry point for signed-in users. The app can analyze either a GitHub-authenticated private repo or a public GitHub URL. That means the backend is the trust boundary for repo cloning, API access, and pushing commits.

11. **Operational and tooling layer**
   The server includes extensive tests and evaluation scripts under `src/**` and `server/scripts`, suggesting the backend is designed for deterministic analysis and agent workflow validation. The repo also contains a `scripts/mock-anthropic.js` helper for local development. Environment examples in both frontend and server indicate a locally run, API-driven system rather than a fully managed deployment.

12. **How the data flows**
   The core flow is: user signs in with GitHub in the frontend, selects a repo, the backend clones it and runs deterministic scanners, results stream back over Socket.IO, the frontend animates building growth, the user opens a building to chat with its specialist agent, the backend analyzes source context and generates changes, the user accepts or rejects them, then the app can verify, commit, and push. Deployment is treated as the final building/agent stage once readiness is high enough.

13. **Key architecture boundaries to capture in a diagram**
   The most important boundaries are:
   - **Browser UI vs server orchestration**
   - **Deterministic scanners vs AI-assisted agents**
   - **Read-only repo analysis vs mutable change queue/sandbox**
   - **HTTP command routes vs realtime Socket.IO updates**
   - **GitHub/Anthropic external services vs Shipyard’s own workflow engine**

Main entry points: [`server/src/routes`](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/routes) (Command Routes), [`server/src/orchestrator`](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/orchestrator) (Orchestrator), [`server/src/scanner`](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/scanner) (Scanner), [`server/src/agents`](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/agents) (AI Agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Router<br/>Next.js entry"]
  node_frontend_scene["City Scene<br/>3D visualization"]
  node_frontend_ui["HUD UI<br/>interaction layer"]
  node_frontend_state["Client State<br/>store/hooks<br/>[useStore.ts]"]
  node_frontend_socket["Socket Context<br/>realtime client<br/>[SocketContext.tsx]"]
  node_frontend_assets[("City Assets<br/>models/fonts/icons")]
end

subgraph group_server["Server"]
  node_server_entry["Server Entry<br/>Express bootstrap<br/>[index.ts]"]
  node_server_routes["Command Routes<br/>HTTP API"]
  node_server_orchestrator["Orchestrator<br/>workflow coordinator"]
  node_server_scanner["Scanner<br/>deterministic analysis"]
  node_server_analyzers["Readiness Analyzers<br/>category checks"]
  node_server_agents["AI Agents<br/>Claude copilots"]
  node_server_prompts["Prompt System<br/>prompt formats"]
  node_server_changes["Change Queue<br/>patch staging"]
  node_server_sandbox["Sandbox<br/>controlled exec"]
  node_server_session["Session Store<br/>auth/session state<br/>[store.ts]"]
end

subgraph group_external["External Services"]
  node_github[("GitHub<br/>external repo host")]
  node_anthropic(("Anthropic API<br/>LLM service"))
end

node_frontend_app -->|"renders"| node_frontend_scene
node_frontend_app -->|"composes"| node_frontend_ui
node_frontend_ui -->|"dispatches"| node_frontend_state
node_frontend_scene -->|"reads state"| node_frontend_state
node_frontend_state -->|"subscribes"| node_frontend_socket
node_frontend_socket -->|"connects"| node_server_entry
node_frontend_ui -->|"calls"| node_server_routes
node_server_entry -->|"mounts"| node_server_routes
node_server_entry -->|"coordinates"| node_server_orchestrator
node_server_routes -->|"auth/session"| node_server_session
node_server_routes -->|"starts scan"| node_server_scanner
node_server_routes -->|"starts agent work"| node_server_agents
node_server_routes -->|"stages changes"| node_server_changes
node_server_routes -->|"verifies"| node_server_sandbox
node_server_orchestrator -->|"runs"| node_server_scanner
node_server_orchestrator -->|"delegates"| node_server_agents
node_server_orchestrator -->|"tracks"| node_server_changes
node_server_scanner -->|"executes"| node_server_analyzers
node_server_agents -->|"formats"| node_server_prompts
node_server_agents -->|"uses"| node_anthropic
node_server_scanner -->|"clones"| node_github
node_server_routes -->|"pushes"| node_github

click node_frontend_app "https://github.com/ryanshabaneh/shipyard/tree/main/frontend/src/app"
click node_frontend_scene "https://github.com/ryanshabaneh/shipyard/tree/main/frontend/src/components/scene"
click node_frontend_ui "https://github.com/ryanshabaneh/shipyard/tree/main/frontend/src/components/ui"
click node_frontend_state "https://github.com/ryanshabaneh/shipyard/blob/main/frontend/src/store/useStore.ts"
click node_frontend_socket "https://github.com/ryanshabaneh/shipyard/blob/main/frontend/src/contexts/SocketContext.tsx"
click node_frontend_assets "https://github.com/ryanshabaneh/shipyard/tree/main/frontend/public/models"
click node_server_entry "https://github.com/ryanshabaneh/shipyard/blob/main/server/src/index.ts"
click node_server_routes "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/routes"
click node_server_orchestrator "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/orchestrator"
click node_server_scanner "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/scanner"
click node_server_analyzers "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/scanner/analyzers"
click node_server_agents "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/agents"
click node_server_prompts "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/agents/prompts"
click node_server_changes "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/changes"
click node_server_sandbox "https://github.com/ryanshabaneh/shipyard/tree/main/server/src/sandbox"
click node_server_session "https://github.com/ryanshabaneh/shipyard/blob/main/server/src/session/store.ts"

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_frontend_app,node_frontend_scene,node_frontend_ui,node_frontend_state,node_frontend_socket,node_frontend_assets toneBlue
class node_server_entry,node_server_routes,node_server_orchestrator,node_server_scanner,node_server_analyzers,node_server_agents,node_server_prompts,node_server_changes,node_server_sandbox,node_server_session toneAmber
class node_github,node_anthropic toneMint
```

## Components

### Frontend

Next.js app that renders the city UI and drives user interaction.

- [App Router](https://github.com/ryanshabaneh/shipyard/tree/main/frontend/src/app): Next.js entry · Top-level routes, layouts, and page entrypoints for the browser app. · `frontend/src/app`
- [City Scene](https://github.com/ryanshabaneh/shipyard/tree/main/frontend/src/components/scene): 3D visualization · 3D city, terrain, camera, clouds, and building variants that represent repo readiness. · `frontend/src/components/scene`
- [HUD UI](https://github.com/ryanshabaneh/shipyard/tree/main/frontend/src/components/ui): interaction layer · Overlays, modals, chat, repo selection, progress, and acceptance controls. · `frontend/src/components/ui`
- [Client State](https://github.com/ryanshabaneh/shipyard/blob/main/frontend/src/store/useStore.ts): store/hooks · Browser store plus hooks for auth, scan flow, socket sync, agent actions, and implementation. · `frontend/src/store/useStore.ts`
- [Socket Context](https://github.com/ryanshabaneh/shipyard/blob/main/frontend/src/contexts/SocketContext.tsx): realtime client · Socket.IO client wrapper that streams backend events into the UI. · `frontend/src/contexts/SocketContext.tsx`
- [City Assets](https://github.com/ryanshabaneh/shipyard/tree/main/frontend/public/models): models/fonts/icons · Public 3D models, fonts, and icon packs used by the city presentation. · `frontend/public/models`

### Server

Express and Socket.IO workflow engine for scans, agents, and repo operations.

- [Server Entry](https://github.com/ryanshabaneh/shipyard/blob/main/server/src/index.ts): Express bootstrap · Backend process entrypoint that wires routes, orchestrator, scanner, and realtime transport. · `server/src/index.ts`
- [Command Routes](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/routes): HTTP API · Route surface for auth, scan, chat, implement, verify, evaluate, export, accept/reject, push, and platform selection. · `server/src/routes`
- [Orchestrator](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/orchestrator): workflow coordinator · Coordinates scan, agent, verification, and change-handling stages across the backend. · `server/src/orchestrator`
- [Scanner](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/scanner): deterministic analysis · Clones target repos and runs production-readiness analyzers to produce stable findings. · `server/src/scanner`
- [Readiness Analyzers](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/scanner/analyzers): category checks · Tests, CI/CD, Docker, docs, env vars, security, logging, and deployment analyzers. · `server/src/scanner/analyzers`
- [AI Agents](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/agents): Claude copilots · Specialist agent layer that uses repo context and scanner findings to propose implementation guidance and edits. · `server/src/agents`
- [Prompt System](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/agents/prompts): prompt formats · Shared prompt templates, response formats, and agent context shaping. · `server/src/agents/prompts`
- [Change Queue](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/changes): patch staging · Queues, exports, and stages proposed changes before acceptance or push. · `server/src/changes`
- [Sandbox](https://github.com/ryanshabaneh/shipyard/tree/main/server/src/sandbox): controlled exec · Restricted execution environment for verification and safe code operations. · `server/src/sandbox`
- [Session Store](https://github.com/ryanshabaneh/shipyard/blob/main/server/src/session/store.ts): auth/session state · Server-side session persistence for authenticated repo workflows. · `server/src/session/store.ts`

### External Services

Third-party systems Shipyard integrates with.

- **GitHub**: external repo host · Source of authenticated repositories, cloning targets, and push destination.
- **Anthropic API**: LLM service · External model provider used by the agent system.

## Connections

- App Router → City Scene: renders · App routes mount the city visualization.
- App Router → HUD UI: composes · Pages and layouts assemble HUD and modal components.
- HUD UI → Client State: dispatches · User actions update browser state and flow control.
- City Scene → Client State: reads state · The city view reflects scan progress and building status.
- Client State → Socket Context: subscribes · Client hooks connect state to realtime backend events.
- Socket Context → Server Entry: connects · Browser establishes Socket.IO realtime communication with the backend.
- HUD UI → Command Routes: calls · HUD actions trigger HTTP commands like scan, chat, implement, accept, and push.
- Server Entry → Command Routes: mounts · Backend entry registers the command surface.
- Server Entry → Orchestrator: coordinates · Requests are handed to the workflow coordinator.
- Command Routes → Session Store: auth/session · Auth and repo context depend on persisted session state.
- Command Routes → Scanner: starts scan · Scan endpoints trigger deterministic repository analysis.
- Command Routes → AI Agents: starts agent work · Chat and implement endpoints invoke specialist agents.
- Command Routes → Change Queue: stages changes · Implement, accept, reject, and export endpoints manage proposed patches.
- Command Routes → Sandbox: verifies · Verification routes use the sandbox for safe execution.
- Orchestrator → Scanner: runs · The orchestrator drives analysis before agent work.
- Orchestrator → AI Agents: delegates · Workflow stages hand contextual tasks to agents.
- Orchestrator → Change Queue: tracks · Orchestrator keeps change staging in sync with the workflow.
- Scanner → Readiness Analyzers: executes · Scanner dispatches the category analyzers.
- AI Agents → Prompt System: formats · Agents rely on shared prompt and response structure.
- AI Agents → Anthropic API: uses · Agent generation is backed by the model provider.
- Scanner → GitHub: clones · Scanner pulls the target repository from GitHub.
- Command Routes → GitHub: pushes · Push endpoints send accepted changes back to the repo host.