ProjectHub

Portfolio-level orchestration plane for managing multiple Claude-driven software projects in parallel from one dashboard.

What It Does

• Dashboard showing all active projects with status, phase, blockers, and next actions
• Project registry with CRUD and project registration form
• Repo ingestion — reads canonical docs (project-plan, execution-index, execution-status, handoff) from managed project repos
• Status model — clear VERIFIED / INFERRED / BLOCKED distinctions derived from repo state
• Claude Code runner — launches Claude Code against project repos with auto-generated prompts
• Continue-driven workflow — resume work with one click, prompts derived from repo docs
• Ticket-targeted launch — target a specific ticket from the project plan
• Run history and logs — full event timeline, stdout/stderr viewer for every execution
• Sync-back — write execution outcomes back to managed repo docs with diff preview

Architecture

• Monorepo: pnpm workspaces + Turborepo
• Backend: Express.js + SQLite (better-sqlite3) — local-first, zero config
• Frontend: React 18 + Vite + React Router + TanStack Query
• Validation: Zod schemas shared between frontend and backend
• Testing: Vitest — 117 tests (16 schema + 98 API/E2E + 3 component)
• Runner: Claude Code CLI via child_process.spawn

Quick Start

cd /Users/gensyn/projecthub
pnpm install
pnpm db:migrate
pnpm db:seed          # optional: load sample projects
pnpm dev              # API on :3100, Web on :5173

Then open http://localhost:5173 to access the dashboard.

Project Structure

apps/
  api/              — Express REST API server
  web/              — React frontend (Vite)
packages/
  shared/           — Shared TypeScript types and Zod schemas
  ui/               — Reusable React components
  config/           — Shared configuration constants
docs/               — Canonical project documentation
  project-plan.md   — Full ticketized implementation plan
  system-architecture.md — Architecture and data flow
  execution-index.md — Current state and next action
  execution-status.md — Verified/inferred/blocked tracking
  claude-code-handoff.md — Restart context
  operator-guide.md — Setup and daily workflow
  repo-contract.md  — Managed repo requirements
  run-lifecycle.md  — How runs work
  project-registry-schema.md — Database schema
  adr/              — Architecture decision records
db/
  migrations/       — SQL migration files
  seeds/            — Seed data
scripts/
  dev/              — Development scripts (migrate)
  seed/             — Seed scripts
test-data/
  sample-projects/  — Fixture repos for testing

API Endpoints

Method	Path	Description
GET	/api/health	Health check
GET	/api/projects	List all projects
POST	/api/projects	Register a project
GET	/api/projects/:id	Get project detail
PUT	/api/projects/:id	Update project
DELETE	/api/projects/:id	Delete project
POST	/api/projects/:id/sync	Sync repo docs into snapshot
GET	/api/projects/:id/snapshot	Get latest repo snapshot
GET	/api/projects/:id/drift	Check drift since last sync
POST	/api/projects/:id/sync-back/preview	Preview sync-back changes
POST	/api/projects/:id/sync-back/apply	Apply sync-back changes
POST	/api/runner/:projectId/launch	Launch a Claude Code run
GET	/api/runner/active	List active runs
POST	/api/runner/:runId/cancel	Cancel an active run
GET	/api/runs/project/:projectId	List runs for project
GET	/api/runs/:id	Get run detail
POST	/api/runs	Create a run record
GET	/api/runs/:id/events	Get run events
POST	/api/backup	Create database backup
GET	/api/backups	List available backups

Managed Repo Contract

ProjectHub reads these files from managed project repos:

File	Purpose
docs/project-plan.md	Ticketized implementation plan
docs/execution-index.md	Current ticket, next action, continue prompt
docs/execution-status.md	Verified/inferred/blocked state
docs/claude-code-handoff.md	Full restart context

Missing files are handled gracefully (status becomes INFERRED).

Testing

pnpm test             # Run all tests
pnpm build            # Build all packages

117 tests across 11 test files:

• 16 schema validation tests
• 13 database CRUD tests
• 11 API endpoint tests
• 12 repo adapter/parser tests
• 5 prompt generator tests
• 8 sync-back tests
• 5 E2E integration tests
• 24 reality-check tests (real repos)
• 18 failure-mode simulation tests
• 2 drift-detector tests
• 3 component tests

Documentation

See docs/ for full documentation:

• Operator Guide — setup and daily workflow
• System Architecture — how it all fits together
• Execution Status — current project state

Status

MVP complete. All 12 implementation tickets are done.