How ryanshabaneh/shipyard works
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: routes Command Routes · orchestrator Orchestrator · scanner Scanner · agents AI Agents
Components 18
Frontend
Next.js app that renders the city UI and drives user interaction.
- App Router · Top-level routes, layouts, and page entrypoints for the browser app.
frontend/src/app - City Scene · 3D city, terrain, camera, clouds, and building variants that represent repo readiness.
frontend/src/components/scene - HUD UI · Overlays, modals, chat, repo selection, progress, and acceptance controls.
frontend/src/components/ui - Client State · Browser store plus hooks for auth, scan flow, socket sync, agent actions, and implementation.
frontend/src/store/useStore.ts - Socket Context · Socket.IO client wrapper that streams backend events into the UI.
frontend/src/contexts/SocketContext.tsx - City Assets · 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 · Backend process entrypoint that wires routes, orchestrator, scanner, and realtime transport.
server/src/index.ts - Command Routes · Route surface for auth, scan, chat, implement, verify, evaluate, export, accept/reject, push, and platform selection.
server/src/routes - Orchestrator · Coordinates scan, agent, verification, and change-handling stages across the backend.
server/src/orchestrator - Scanner · Clones target repos and runs production-readiness analyzers to produce stable findings.
server/src/scanner - Readiness Analyzers · Tests, CI/CD, Docker, docs, env vars, security, logging, and deployment analyzers.
server/src/scanner/analyzers - AI Agents · Specialist agent layer that uses repo context and scanner findings to propose implementation guidance and edits.
server/src/agents - Prompt System · Shared prompt templates, response formats, and agent context shaping.
server/src/agents/prompts - Change Queue · Queues, exports, and stages proposed changes before acceptance or push.
server/src/changes - Sandbox · Restricted execution environment for verification and safe code operations.
server/src/sandbox - Session Store · Server-side session persistence for authenticated repo workflows.
server/src/session/store.ts
External Services
Third-party systems Shipyard integrates with.
- GitHub · Source of authenticated repositories, cloning targets, and push destination.
- Anthropic API · External model provider used by the agent system.
Connections 22
- 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.