System architecture

Galapagos separates the local search library from the Hub registry while letting them share task and scaffold card schemas.

CLI / Python library ── task + scaffold bundles ─┐
Browser ─────────────── Hub API requests ────────┼─> FastAPI ─> Postgres / SQLite metadata
Browser Discovery Space ─ provider key + run ───┘           └─> HF Bucket / local artifacts
                                                              └─> review state + leaderboard
Next.js frontend ── same-origin /api proxy ────────────────────┘

Current responsibilities

Layer	Technology	Current responsibility
Website	Next.js 14, React 18, TypeScript, Tailwind	Hub browsing, Discovery Space, trajectory UI, accounts, leaderboard.
API	FastAPI, Pydantic, SQLAlchemy	Card validation, metadata, uploads, file serving, live-run streams, review-state transitions.
Metadata	Postgres; SQLite in local development	Users, tokens, scaffold/task/discovery rows, likes, review state, leaderboard rows.
Artifact storage	Hugging Face Storage Buckets; local community directory in development	Uploaded task/scaffold repos and discovery bundles.
Identity	Supabase Auth plus Galapagos API tokens	Browser identity and authenticated write requests.

API token scopes are recorded but are not currently enforced per route. The Hub stores uploaded controller/evaluator source as artifacts and does not import community code into hosted runners.

Card and artifact flows

Task and scaffold submission

galapagos submit --repo-type task|scaffold --card-path ...
  → POST /api/tasks/upload or /api/scaffolds/upload
  → validate card and bundle paths
  → write artifact bytes
  → write/update metadata row

The CLI currently supports these two repository types only. A community scaffold repo is browsable and downloadable, but the server does not execute its controller.

Discovery submission

Browser Discovery Space                   Direct API client
  → POST /api/discovery/run                 → POST /api/discoveries/upload
  → stream a bundled hosted run             → upload card + solution + trajectory
  → publish completed bundle              both → Discovery(review_status="pending")

There is no discovery mode in galapagos submit. Hosted Discovery Space runs use the scaffolds and providers advertised by GET /api/discovery/options; claude_code and meta_harness are local-only.

The published hosted-run bundle uses these paths when the artifacts exist:

card.yaml
trajectory/evolutionary_trajectory.jsonl
solution/solution.<suffix>
solution/best_program_info.json
config/config.yaml
evaluation/run.json
evaluation/final_evaluation.json
evaluation/verification.json

Review and leaderboard promotion

Discovery(pending)
  → POST /api/discoveries/{name}/review {status: accepted|rejected}
  → accepted: copy/update submitted score in LeaderboardEntry

This endpoint is a state transition and promotion operation. It does not automatically replay a trajectory, run an evaluator, enforce reviewer identity, or establish parity. Deployments that require those checks must perform them before issuing the review action.

Direct POST /api/leaderboard submissions similarly land pending; the verify endpoint only updates their surfaced status.

Runtime services

• The Next.js frontend serves pages and proxies /api/* to FastAPI.
• FastAPI owns validation, authentication checks, storage access, live-run orchestration, and review state.
• Postgres/SQLite is the metadata source of truth.
• Hugging Face Buckets/local storage hold repository bytes; metadata rows store a backend and URI pointing to them.
• The hosted live-run services execute bundled scaffold/task code only. Model-generated candidate code is handed to the task evaluator according to the run's local/Docker evaluation mode.

Deployment shape

Public Next.js service
  ├─ static/pages
  ├─ /api/*  → private FastAPI service
  └─ /docs/* → built MkDocs output

Private FastAPI service
  ├─ Postgres metadata
  ├─ Hugging Face Storage Buckets
  └─ Supabase Auth verification

For environment variables and production setup, see hub/README.md and hub/DEPLOY.md.