Orca

# MISSION: Scaffold "Orca" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Orca**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Orca
- **What It Does**: Orca is an open-source agentic development environment (ADE) for running Claude Code, Codex, OpenCode or Pi side by side, each in its own git worktree and terminal. It ships as an Electron desktop app with a mobile companion and a cloud relay.
- **Domain & Category**: Agentic Development Environment for Parallel Coding Agents
- **Production Scale**: 6-20 people
- **Development Mode**: HYBRID
- **Architectural Rationale**: Agent CLIs stay the user's own. Orca adds the orchestration layer around them: isolated git worktrees, a PTY daemon that outlives the UI, and a relay for mobile steering. It can support new agents without bundling them.
- **Live Website Reference**: https://onOrca.dev
- **Source Repository**: https://github.com/stablyai/orca
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Electron, React, Zustand, Vite, Node.js, Expo, React Native, Hono, PostgreSQL, Terraform, Google Cloud, Docker, Vitest, Playwright, pnpm, GitHub Actions
- **Primary Language(s)**: TypeScript, JavaScript, Swift, CSS, HCL, Kotlin
- **License of the reference repo**: MIT
- **Frontend**: Electron — Desktop shell for macOS, Windows and Linux built with electron-vite and electron-builder; React — Renderer UI (src/renderer) for worktrees, terminals and agent panes, audited with react-doctor; Zustand — Renderer state stores, with a selector fan-out benchmark enforced as a check; Vite — Bundler for the renderer and a browser build of the UI (vite.web.config.ts); Expo — iOS and Android companion app (Expo Router, xterm webview, notifications) released with fastlane
- **Backend & APIs**: Node.js — Electron main process, the orca CLI (src/cli) and the orcad runtime daemon that hosts PTYs; node-pty — Native pseudo-terminals for each agent session (built during install); Hono — HTTP layer of the cloud relay and push services in cloud/apps
- **Data & persistence**: PostgreSQL — Relay and push state accessed with pg, with shared schema in cloud/packages/postgres-schema
- **Infrastructure & deploy**: Terraform — Infrastructure as code for the relay under cloud/infra, also bundled into the fence-broker image; Google Cloud — Relay deploy target (Cloud SQL, GCE candidates) driven by many cloud-* workflows; Docker — Container images for relay, push and fence-broker plus daemon lifecycle test images; Vitest — Unit, contract and performance-contract tests (config/vitest.config.ts); Playwright — End-to-end desktop and packaged-browser tests in tests/e2e; GitHub Actions — 60+ workflows for PR checks, per-OS builds, mobile releases and relay operations
- **Tooling, testing & ops**: Claude Agent SDK — Drives Claude Code sessions using the user's own installed Claude CLI binary; Git worktrees — Each agent runs in its own isolated git worktree so parallel attempts can be compared and merged
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/stablyai/orca @ 646e9a5)
1. **One git worktree per agent, orchestrated from one desktop app**: The README and skill-guides/orchestration.md describe fanning one prompt across several agents (Claude Code, Codex, OpenCode, Pi), each in its own isolated git worktree, then comparing results and merging the winner.
2. **Bring-your-own agent CLIs instead of bundling them**: pnpm-workspace.yaml lists every @anthropic-ai/claude-agent-sdk platform binary under ignoredOptionalDependencies, so Orca always launches the user's own resolved Claude CLI instead of shipping about 95 MB per platform.
3. **A separate runtime daemon hosts terminals**: build:orcad and the smoke:orcad-terminal script build a daemon (orcad) that owns the node-pty sessions, and config/docker has test images for daemon scope, lifetime and shutdown of descendant processes, so terminals survive UI restarts and updates.
4. **Cloud relay for the mobile companion, on its own pnpm workspace**: cloud/ is a separate pnpm workspace with relay, push, relay-ops and relay-fence-broker apps (Hono, pg, ws, tweetnacl, jose), deployed to Google Cloud with Terraform through dozens of cloud-deploy/monitor/operate workflows.
5. **Lint ratchets and reliability gates as policy**: package.json lint chains oxlint configs (anti-slop, type-aware, design-system, dead classes) with ratchet checks on max lines, ts-nocheck and runtime-electron baselines stored in config/*-baseline.txt, plus config/reliability-gates.jsonc.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Vite 6 with TanStack Router for fully type-safe routing. Manage server state and caching via TanStack Query v5 with optimistic UI updates.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.