Architecture

Architecture

Canonical architecture: docs/ARCHITECTURE.md. This page is the hosted operator-oriented companion and must not redefine the API route list or product scope.

System context

flowchart TB
  subgraph Browser
    PF[ProjectFlow]
    LAB[Darwin Lab browser workers]
    UI[Darwin control room]
    TC[Telemetry client]
  end

  subgraph Cloudflare
    API[Darwin Worker API]
    D1[(D1)]
    PAGES[Darwin Pages]
  end

  subgraph Providers
    OAI[OpenAI Responses API]
    GH[GitHub API and Actions]
    PREVIEW[ProjectFlow preview deployment]
  end

  PF --> TC
  LAB -->|real target actions| PF
  TC --> API
  UI --> API
  PAGES --> UI
  API <--> D1
  API --> OAI
  API --> GH
  GH --> PREVIEW
  GH --> API

Loading

Ownership boundaries

Darwin repository

Darwin owns:

• the control room UI;
• telemetry contracts and ingestion;
• event persistence and aggregation;
• deterministic evidence parsing;
• GPT prompt/context assembly and output validation;
• manifest construction;
• GitHub workflow dispatch, execution state, release, and rollback records.

ProjectFlow repository

ProjectFlow owns:

• target product source;
• darwin.target.json;
• semantic instrumentation integration;
• mutation and rollback workflows;
• protected/mutable path enforcement;
• validation commands and change budgets;
• preview and production deployment.

This division ensures the target repository enforces its own policy even when Darwin proposes the work.

Target snapshot

When a target is verified, Darwin:

1. resolves the configured branch to a 40-character commit SHA;
2. reads darwin.target.json from that exact SHA;
3. validates the application inventory, mutable/protected areas, source paths, commands, and budgets;
4. reads only approved context files from the same SHA;
5. canonicalizes and hashes the source context;
6. verifies that the configured study deployment responds as ProjectFlow;
7. stores the repository-derived application map with the SHA and source hash;
8. admits evidence only when every event reports the connected commit-derived application version.

The evidence pack, GPT analysis, and Codex manifest retain the base SHA and source hash. Mixed-version cohorts and stale telemetry fail closed. A changed target requires a new repository snapshot and analysis.

Durable data

D1 tables currently store:

Table	Purpose
telemetry_events	ordered semantic events and receipt metadata
participant_workspaces	anonymous ProjectFlow study workspace state
analysis_runs	deterministic evidence packs
evidence_analyses	validated GPT portfolios and cache metadata
codex_manifests	immutable approved implementation manifests
repository_executions	workflow, diff, checks, PR, preview, release, rollback
reset_executions	baseline workflow, validation, deployment verification
outcome_validations	versioned measured fitness outcomes and cohort hashes
demo_state	evolution cycle state
target_connections	verified target snapshot and checks
operational_events	30-day redacted audit transitions and provider metrics
lab_experiments	versioned tasks, lifecycle, hashes, and provenance
lab_agent_runs	append-only isolated browser-run outcomes
lab_agent_actions	idempotent semantic action observations
lab_evidence_records	immutable hashed Darwin Lab evidence
lab_analyses	evidence-citing Lab GPT portfolios
lab_selection_results	human-approved Lab mutation selection

In-memory implementations support local tests and development without D1.

State machines

Mutation execution:

prepared -> queued -> codex_running -> validating
         -> pull_request_open -> preview_ready -> releasing
         -> deployment_verifying -> released
         -> failed (from any non-terminal stage)

Rollback execution:

prepared -> queued -> validating -> pull_request_open
         -> preview_ready -> releasing -> released
         -> failed (from any non-terminal stage)

Demo reset:

queued -> running -> validating -> deploying -> complete
       -> failed (from any non-terminal stage)

Only an explicit release call merges a reviewed pull request. Candidate previews never replace production automatically. After merge, Darwin polls the configured ProjectFlow study deployment for semantic commit and app-version metadata. The execution remains deployment-ready until both match the merge result; only then does Darwin record released and start the next evidence cycle at the verified deployment timestamp. Evidence generation rejects mixed-version measurement windows.

Reset uses the same signed, execution-scoped callback boundary. Darwin retains telemetry, evidence, analyses, manifests, and Genome history while the reset is queued, running, validating, or deploying. It clears that state only after production reports the exact restored baseline commit, then anchors the clean baseline cycle at the verified deployment timestamp. Failures remain persisted and retryable.

Darwin Lab experiments use compare-and-swap lifecycle transitions plus append-only, idempotent runs and actions. Evidence is derived only after terminal run state is durable. Cancellation, retry, archival, and force-fail recovery keep stranded work inspectable. The darwin_lab provenance record survives every artifact and is never inferred from a study-name convention.

Generated reasoning context

scripts/generate-reasoning-context.mjs combines the versioned prompt material and mutation examples into workers/api/src/reasoning/generated-context.ts. npm run typecheck verifies that the generated file is current; npm run build regenerates it.

Known architectural hardening

The public Build Week deployment now has capability-scoped operator authorization, HMAC-authenticated ProjectFlow ingestion, protected read APIs, execution-scoped signed repository callbacks with replay protection, atomic release transitions, and deployment-aware evidence cycles. It remains a controlled hackathon proof of life rather than a production trust boundary.

See Security and Privacy, the generated API route reference, and the issue backlog.