Skip to content

Architectural Blueprint & Implementation Plan: Idea → Done Conductor (ship.rafaelgonzalezalbes.com)

  • Document Version: v1.1.0
  • Target Host: https://ship.rafaelgonzalezalbes.com (Infra VPS 85.215.32.166)
  • Staging Bays Target: https://testing1..3.rafaelgonzalezalbes.com (Apps VPS 82.165.177.110)
  • Status: Living blueprint — Phases 1–3/6–7 live on ship.*; see hardening table in idea-to-done.md
  • Related Documents: Idea → Done Conductor Architecture, Platform Overview, MCP Stack Overview

1. Executive Summary & Purpose

The Idea → Done Conductor is the central orchestrator that transforms high-level product ideas into live, verified production features across your infrastructure.

While existing platform tools (Plane for project management, Forgejo for Git repositories, Woodpecker for CI/CD, Netdata/Kuma for metrics/status) manage individual operational layers, the Conductor (ship.*) acts as the overarching control tower. It bridges the gap between AI-driven task generation, human approval gates, automated preview staging bays, and zero-downtime production deployment.

This document provides a concrete, multi-phase engineering blueprint specifying where components will live, how data flows, which interfaces/APIs are consumed, and how the system will be built incrementally.

2. Platform Component Topology

flowchart TB
  subgraph UserInterface [Human & Agent Control Layer]
    PM[You / PM]
    CursorAgent[Cursor IDE / Local Agent]
    ShipUI["Ship Dashboard (ship.rafaelgonzalezalbes.com)"]
  end

  subgraph OrchestrationLayer [Infra VPS - 85.215.32.166]
    ShipCore[Ship Conductor Engine - Node.js/Go]
    StateStore["Shared State Store (SQLite / JSON / Plane)"]
    SecretsBroker[Secrets Broker & SOPS Manager]
    Bridge["Plane-Forgejo Bridge (bridge.*)"]

    ShipCore --> StateStore & SecretsBroker & Bridge
  end

  subgraph ServiceStack [Self-Hosted Core Services]
    Plane["Plane PM (pm.*)"]
    Forgejo["Forgejo Git (git.*)"]
    Woodpecker["Woodpecker CI (ci.*)"]
    DefectDojo["DefectDojo (security.*)"]
    Netdata["Netdata Metrics (metrics.*)"]
    Kuma["Uptime Kuma (status.*)"]
  end

  subgraph ExecutionLayer [Apps VPS - 82.165.177.110]
    StagingBays["Staging Bays (testing1..3.*)"]
    AppsProd["Live Apps (wearlab.*)"]
    AppsNetdata[Netdata Child Agent]
  end

  ShipUI --> ShipCore
  CursorAgent -->|MCP / API| ShipCore
  ShipCore -->|HTTP API| Plane & Forgejo & Woodpecker & DefectDojo & Kuma
  ShipCore -->|SSH / Traefik API| StagingBays
  StagingBays -.->|Metrics| AppsNetdata

3. Technology Stack & Integration Architecture

Module Location Technology / Tooling Responsibility
Ship Web UI Infra VPS (85.215.32.166) Vite + React (Lightweight SPA behind Traefik) Visual Status Board: Initiative radar, ticket stages, waiting_on reasons, testing slot links, merge buttons, wallet/cost gauges.
Ship Orchestrator Service Infra VPS (/opt/devops/ship) Node.js (TypeScript) or Go microservice Core state engine, cron timers, event listeners, webhook dispatchers, worker queue.
State Storage (H1) Infra VPS Embedded SQLite / JSON (/opt/devops/ship/data/state.sqlite) + Plane custom fields Fast machine-readable ticket state (stage, waiting_on, slot, pr_url, retry_count).
Secrets Broker (D25) Infra VPS SOPS + tmpfs RAM disk (/run/ship-secrets/) Decrypts Plane A (LLM keys) and staging credentials into volatile RAM; injects tmpfs env files into Apps VPS over SSH.
Staging Controller (H2) Apps VPS (82.165.177.110) Bash / Python scripts + Traefik Labels Manages claim, deploy, and wipe operations for testing1, testing2, and testing3 bays.
LLM Price Catalog (D27d) Infra VPS Cron worker + OpenRouter Models API Periodically fetches token rates; updates /opt/devops/ship/config/price-catalog.json.

4. Phase-by-Phase Implementation Roadmap

The implementation is broken down into 5 progressive phases, starting with zero-code manual dry-runs and culminating in full orchestrator automation.

gantt
  title Implementation Roadmap Timeline
  dateFormat  YYYY-MM-DD
  section Phase 1
  H12 Manual Dry-Run & File Schema        :p1, 2026-08-10, 5d
  section Phase 2
  H1 State & H2 Staging Scripts on Apps   :p2, 2026-08-15, 7d
  section Phase 3
  Ship Status Board MVP (ship.*)          :p3, 2026-08-22, 10d
  section Phase 4
  Auto-Dispatch & FinOps Wallet (H31)    :p4, 2026-09-01, 10d
  section Phase 5
  Hardening Extensions (H2b-H18b)         :p5, 2026-09-11, 14d

Phase 1: Golden-Path Manual Dry-Run (H12) — [COMPLETED & VERIFIED]

Objective: Prove the handoff flow without writing web UI code.

  1. Protocol Definition: Established standardized markdown file local/initiatives/001-golden-path-dryrun.md in infra-devops.
  2. Execution & Validation:
  3. Created single-ticket review pack for INFRA-101 (docs/architecture/overview.md).
  4. Ran simulation and validation inside containerized Docker tool runner (docker-compose.tools.yml).
  5. Applied documentation update, generated receipt rcpt-20260804-infra101, and verified build.

Phase 2: Core Infrastructure Plumbing (H1, H2, D25) — [COMPLETED & VERIFIED]

Objective: Deploy machine-readable state tracking and staging bay management.

  1. Staging Controller Scripts (H2):
  2. Created scripts/slot-manager.sh with subcommands claim, deploy, wipe, and status.
  3. Supports dynamic Traefik route generation with tenant Clear-Site-Data headers (H2b).
  4. State Store (H1):
  5. Created SQLite initializer scripts/init-state-db.py deploying local/data/state.sqlite with WAL mode enabled.
  6. Verification Suite:
  7. Created containerized test suite scripts/verify-phase2-plumbing.py validating full slot claim/wipe mechanics.

Phase 3: Ship Status Board MVP (ship.rafaelgonzalezalbes.com) — [LIVE IN PRODUCTION]

Objective: Provide a centralized visibility UI for human tracking and gate actions.

  1. Reverse Proxy & Deployment:
  2. Target host live at https://ship.rafaelgonzalezalbes.com.
  3. Containerized service ship-conductor deployed via docker-compose.yml behind Traefik reverse proxy with Let's Encrypt TLS.
  4. Frontend UI & Fastify Backend:
  5. Fastify REST API daemon ship/server.js with auto-table initialization.
  6. Single-page dashboard UI ship/public/index.html displaying active initiatives, ticket status cards, FinOps wallet tracker (H31), system receipts log (H6), and interactive approval gate buttons.

Phase 4: Auto-Dispatch, FinOps Wallet & Price Catalog (D27, H31, W4) — [PARTIAL]

Objective: Automate worker dispatching and enforce strict financial boundaries.

  1. Price Catalog Ingestion (D27d):
  2. Created scripts/sync-price-catalog.py fetching 338+ live models from OpenRouter API (https://openrouter.ai/api/v1/models).
  3. Stores model prices and fallback cost bands in local/data/price-catalog.json.
  4. Wallet Guardrail Engine (H31):
  5. Created scripts/finops-wallet-engine.py tracking monthly cumulative spend against ~€30.00 soft limit.
  6. Locks ticket dispatches (waiting_on: budget) when limit is reached.
  7. Worker Dispatcher Service (W4):
  8. CLI companion scripts/auto-dispatcher.py; live path is Ship board Dispatch scan / Work T1 (H8 packs) + Phase 7 job queue / ship-worker-runner.mjs. Full Cursor IDE spawn still optional (SHIP_WORKER_SPAWN_URL).

Phase 5: Workflow Hardening & Advanced Protections (H2c, H7d, H9b, H9c) — [PARTIAL]

Objective: Integrate safety nets, automated rollbacks, and developer experience tools.

  1. Staging Tenant Isolation & Reclamation (H2b, H2c):
  2. Injected tenant Clear-Site-Data headers on Traefik staging routes (slot-manager.sh).
  3. scripts/reclaim-idle-slots.py + cron template templates/apps-vps/cron.d/ship-reclaim-slots (install on Apps still optional).
  4. Flake Isolator (H7d):
  5. scripts/flake-isolator.py — zero-token retries for transient 502/504 (not board-wired).
  6. Pre-Flight Health Gate & Instant 5xx Auto-Rollback (H9b, H9c):
  7. H9b shipped: Ship staging_deploy calls Apps slot-manager.sh preflight (MemAvailable) before claim/deploy.
  8. H9c locked: auto-rollback on 5xx still not board-wired (depends on H5 redeploy + Kuma hooks).

Phase 6: Ship board conductor spine (H3–H15, W4, D19b v1) — [LIVE ON ship.*]

Objective: Make Idea → Done operable from the board without claiming full auto workers.

  1. DoD / receipts / stuck / retries / gates / rollback / freeze — live on ship.rafaelgonzalezalbes.com.
  2. H8 context pack + W4 dispatch scan + H9 pause/cancel/resume + H15 path conflict — Ship API + UI.
  3. D19b v1 — worker session strip + scripts/ship-work-t1.mjs; Phase 7 adds job queue + runner (still no full Cursor IDE spawn).
  4. Status of truth: hardening table in idea-to-done.md (Shipped / Partial / Locked); runbook ship-golden-path.md.

Phase 7: D25 / H9b / D19b jobs / Layer 2–3 polish — [LIVE 2026-08-05]

  1. Staging secrets inject/wipe/reveal via slot-manager (/run/testing-slots/<slot>.env or ~/staging/run/testing-slots/<slot>.env fallback).
  2. Ship staging_deploy runs Apps preflight (H9b) before claim/deploy.
  3. Worker job queue + scripts/ship-worker-runner.mjs + docker ship-worker poller; OpenRouter coding inside allowed_paths when key installed (local/install-ship-openrouter-key.sh).
  4. Board: Away (H21), grouped actions, wallet strip, H28 evidence upload.

Phase 8: Cursor Agent SDK / agree UI — [NEXT]

  1. Optional Agent SDK session spawn from H8 pack.
  2. Layer 4 discovery/agree forms on ship.*.
  3. H9c auto-rollback when H5 redeploy + Kuma hooks land.

5. Deep Technical Specifications

5.1 Machine-Readable State Database Schema (H1)

Location: /opt/devops/ship/data/state.sqlite on Infra VPS (85.215.32.166).

CREATE TABLE initiatives (
  id TEXT PRIMARY KEY,               -- e.g. "init-2026-08-portfolio-cta"
  title TEXT NOT NULL,
  repo TEXT NOT NULL,                -- e.g. "rafael.gonzalez.albes/portfolio"
  blast_radius TEXT NOT NULL,        -- "docs" | "app" | "infra" | "secrets"
  cost_band TEXT NOT NULL,           -- "less" | "mid" | "more"
  time_band TEXT NOT NULL,           -- "soon" | "days" | "longer"
  stage TEXT NOT NULL,               -- "discovery" | "agree" | "execution" | "done"
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE tickets (
  id TEXT PRIMARY KEY,               -- e.g. "PORT-42"
  initiative_id TEXT NOT NULL,
  plane_issue_id TEXT NOT NULL,
  title TEXT NOT NULL,
  sequence_order INTEGER NOT NULL,
  stage TEXT NOT NULL,               -- "queued" | "execute" | "ci" | "staging_test" | "ready_to_merge" | "ship" | "live_verify" | "done"
  waiting_on TEXT,                   -- "human_agree" | "human_test" | "human_merge" | "resources_apps" | "budget" | "slot_busy" | "ci"
  branch_name TEXT,                  -- e.g. "ship/init-2026-08/PORT-42-cta"
  pr_url TEXT,
  assigned_slot TEXT,                -- "testing1" | "testing2" | "testing3" | NULL
  retry_count INTEGER DEFAULT 0,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY(initiative_id) REFERENCES initiatives(id)
);

CREATE TABLE slot_claims (
  slot_name TEXT PRIMARY KEY,        -- "testing1", "testing2", "testing3"
  ticket_id TEXT UNIQUE,
  app_type TEXT NOT NULL,            -- "portfolio" | "wearlab" | "docs"
  claimed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  expires_at TIMESTAMP,              -- H2c 24h idle reclamation
  FOREIGN KEY(ticket_id) REFERENCES tickets(id)
);

5.2 Staging Slot Controller Specification (H2)

Location: /opt/apps/scripts/slot-manager.sh on Apps VPS (82.165.177.110).

Subcommands interface specification:

  1. slot-manager.sh claim <slot> <ticket_id> <app_type>
  2. Checks /opt/apps/slots/<slot>/status.json. If claimed, exits with code 42 (SLOT_BUSY).

  3. Creates /run/slots/<slot>/ in tmpfs. Writes status.json with owner details and timestamps.

  4. slot-manager.sh deploy <slot> <git_repo> <commit_sha> <env_tmpfs_path>

  5. Clones target commit SHA into /opt/apps/slots/<slot>/workspace/.
  6. Copies staging environment variables from <env_tmpfs_path> to /opt/apps/slots/<slot>/workspace/.env.
  7. Generates dynamic Traefik route config in /opt/apps/traefik/dynamic/<slot>.yml: 
    http:
  routers:
    testing1:
      rule: "Host(`testing1.rafaelgonzalezalbes.com`)"
      service: "testing1-service"
      middlewares: ["clear-site-data"]
  middlewares:
    clear-site-data:
      headers:
        customResponseHeaders:
          Clear-Site-Data: '"cache", "cookies", "storage"'

  8. Executes docker compose -f /opt/apps/slots/<slot>/workspace/docker-compose.yml up -d --build.

  9. slot-manager.sh wipe <slot>

  10. Executes docker compose -f /opt/apps/slots/<slot>/workspace/docker-compose.yml down -v --remove-orphans.
  11. Removes /opt/apps/slots/<slot>/workspace/ and dynamic Traefik router config.
  12. Clears /run/slots/<slot>/ in tmpfs.

5.3 Event & Webhook Integration Routing

sequenceDiagram
  participant Human as You (PM)
  participant Ship as Ship Conductor (ship.*)
  participant Forgejo as Forgejo Git (git.*)
  participant Woodpecker as Woodpecker CI (ci.*)
  participant AppsVPS as Apps VPS (82.165.177.110)

  Human->>Ship: Approve Review Pack
  Ship->>Forgejo: Create Branch ship/init-1/T1
  Ship->>Forgejo: Dispatch Worker -> Open PR #12
  Forgejo->>Woodpecker: Webhook: pull_request created
  Woodpecker->>Woodpecker: Run Lint + Trivy + Build
  Woodpecker->>Ship: Webhook: pipeline status = SUCCESS
  Ship->>AppsVPS: SSH: slot-manager.sh claim testing1 T1 portfolio
  Ship->>AppsVPS: SSH: slot-manager.sh deploy testing1 ...
  AppsVPS-->>Ship: Deploy ready (HTTP 200 OK)
  Ship->>Human: Ping Gate: "T1 ready on testing1.rafaelgonzalezalbes.com"

5.4 Security Hardening & Zero-Root SSH Pipeline (D25)

Security is non-negotiable. All automation between Infra VPS and Apps VPS strictly enforces least-privilege access, zero root SSH, and volatile in-memory credentials:

  1. Zero-Root SSH Policy (Enforced):
  2. Root login is permanently blocked across all nodes (PermitRootLogin no, PasswordAuthentication no in /etc/ssh/sshd_config).

  3. Human administration requires personal unprivileged accounts + passphrase-protected SSH keys.

  4. Dedicated Bot Service Account & Forced Command Lock:

  5. Cross-server communication uses an unprivileged ship-bot service account.
  6. A dedicated Ed25519 SSH key pair is generated for worker-to-vps commands: /opt/devops/ship/keys/ship_bot_ed25519.
  7. On Apps VPS (82.165.177.110), /home/deploy/.ssh/authorized_keys forces strict command isolation: 
    command="/opt/apps/scripts/slot-manager.sh $SSH_ORIGINAL_COMMAND",no-port-forwarding,no-x11-forwarding,no-agent-forwarding ssh-ed25519 AAAAC3... ship-conductor-bot

  8. Security Result: The bot key CANNOT open a shell, CANNOT view files outside /opt/apps/slots/, and CAN ONLY trigger pre-approved slot-manager.sh subcommands (claim, deploy, wipe).

  9. Plane A Secrets (Worker Platform):

  10. Stored in secrets/ship-workers.enc.env on Infra VPS (SOPS encrypted).
  11. Decrypted strictly into volatile RAM (/run/ship-secrets/platform.env, tmpfs, chmod 600) when ship-conductor starts.

  12. Never written to disk, git, or build logs.

  13. Plane B Secrets (Staging / Target App):

  14. Ephemeral staging passwords / tokens generated per claim.
  15. Written directly to Infra VPS tmpfs: /run/ship-secrets/slots/<slot>.env.
  16. Transferred over SSH tunnel into Apps VPS tmpfs: /run/slots/<slot>/staging.env.
  17. On Release/Wipe: tmpfs paths wiped on both servers; generated staging tokens revoked.

6. Verification & Acceptance Criteria

Each implementation phase must pass strict verification before proceeding to the next:

  • State Verification: curl https://ship.rafaelgonzalezalbes.com/api/v1/state returns valid JSON reflecting accurate ticket status.
  • Staging Verification: Executing slot-manager.sh wipe testing1 leaves zero orphan containers or leftover .env files on Apps VPS.
  • Security Verification: No plaintext API keys or database passwords appear in git commits, Plane comments, or Woodpecker build logs.
  • Budget Verification: Simulating an LLM 429 quota error immediately sets ticket stage to waiting_on: budget without infinite retries.

7. Synthesis of Industry Field Reports & Architectural Lessons

The design of the Idea → Done Conductor (ship.*) incorporates key learnings synthesized from real-world production multi-agent systems (Vedant Parmar Singh, MindStudio, EPAM Octobots, APM):

7.1 "System Controls Workflow, Not Agent" (MindStudio & EPAM)

  • Worker agents must never make workflow-level decisions (such as skipping CI, deploying to production, or modifying ticket scopes unilaterally).
  • The central orchestrator (ship.*) enforces state machine transitions and gate approvals.

7.2 Spec-First Development & Micro-Packs (Vedant & APM)

  • Agents given vague prompts make unprompted decisions and burn tokens.
  • Execution requires a strict Agreement Review Pack (Stage 2) before coding, and a Micro-Agreement Pack (D23f) before applying fix loops during staging test gates.

7.3 Per-Worker Staging Isolation & Full Folder Clones (EPAM Octobots)

  • Fragile shared git worktrees across multi-repo/microservice workspace roots fail.
  • Each staging bay (testing1..3) receives an isolated workspace folder with a complete repo clone, while shared runtimes (databases, .env RAM paths) are mounted cleanly.

7.4 Zero-Dependency IPC: SQLite WAL Mode (EPAM & MindStudio)

  • Complex WebSockets or heavy Redis message brokers add unnecessary RAM overhead on small VPS nodes.
  • A single SQLite database in WAL mode (state.sqlite) with a light CLI/API wrapper handles concurrent agent reads and writes cleanly (< 50MB RAM footprint).

7.5 Evidence-Obsessed QA & Machine Receipts (Vedant & MindStudio)

  • Workers write structured machine receipts (H6) containing branch names, PR links, and Woodpecker build IDs.
  • worker-qa attaches screenshots/logs to tickets before triggering human test gates (H28).

7.6 FinOps Tiering & Hard Spend Stops (Vedant & MindStudio)

  • Tier models by role complexity (Less: local/cheap; Mid: Groq/Flash; More: Sonnet/GPT-4).
  • Enforce hard spend stops (prepaid balance, workspace cap, OpenRouter guardrails) to prevent autonomous token burning under a soft ~€30/month wallet.