RepoFinisher
RepoFinisher is a repository-completion operating system. It inspects incomplete or partially working repositories, infers intended product behavior from evidence, measures completion and production readiness, creates approval-bound implementation plans, executes approved changes on isolated branches, validates the result, performs bounded repair, rescoring, and operational learning, and can continue iterating until explicit completion targets are reached or a safe stop condition applies.
Canonical production architecture
The authorized production architecture is below. The Contabo cutover remains in progress until runtime and authenticated-flow checks pass:
- Frontend:
artifacts/repo-finisher (React/Vite) on Vercel.
- API/control plane:
artifacts/api-server (Express) on Contabo as repofinisher-api.
- Long-running completion worker: the same API/worker codebase on Contabo as
repofinisher-worker, using the persistent persistent-worker.mjs entrypoint.
- Authentication and database: Supabase.
- Durable execution state and RLS: Supabase Postgres.
- User AI credentials: Supabase Vault where supported by the trusted backend path.
- Source control and CI: GitHub + GitHub Actions.
- Observability: Sentry when configured, plus Vercel and Contabo runtime/build logs.
Canonical frontend:
https://portfolio.donmatthews.live
Contabo API hostname:
https://api.portfolio.donmatthews.live
Canonical API hostname:
https://api.portfolio.donmatthews.live
Railway is shut down and is not an approved runtime. Cloud Run is retired infrastructure. Files and notes that reference it are migration history only and must not be treated as current production architecture.
Runtime flow
- The browser loads the Vite SPA from Vercel.
- Supabase handles user authentication and GitHub OAuth.
- The SPA calls the Contabo API with the user's Supabase bearer token.
- The Contabo API reads/writes durable state in Supabase and performs trusted server-side operations.
- Finish-until-target work is persisted as an active completion session in Supabase.
- The Contabo worker polls durable session state, claims work using the existing lease/heartbeat contract, executes bounded work, and releases the lease.
- GitHub remains the source of truth for repository state, branches, draft PRs, CI evidence, and commit history.
Core capabilities
RepoFinisher includes or is designed to include:
- full-portfolio repository discovery and prioritization;
- completion and production-readiness scoring;
- confidence-adjusted valuation and opportunity analysis;
- source-backed competitor/pricing/feature research;
- evidence-driven multi-stage reasoning;
- explicit plan approval and base-SHA binding;
- isolated branches and draft pull requests;
- CI/runtime verification;
- bounded self-healing repair;
- iterative finish-until-target sessions;
- operational learning based on measured outcomes;
- external coding-agent handoffs.
Repository layout
artifacts/
api-server/ Express API + Contabo worker entrypoints
repo-finisher/ React/Vite frontend deployed on Vercel
repo-finisher-mobile/ Mobile artifact
mockup-sandbox/ Non-production sandbox
lib/ Shared repository intelligence and API packages
supabase/migrations/ Forward-only database migrations
docs/ Architecture, operations, state, policy, runbooks
.github/workflows/ CI and production verification
Dockerfile.apiserver Contabo API/worker image
vercel.json Vercel frontend build/routing configuration
Development
Requirements:
- Node.js 20+
- pnpm
9.15.9
- Supabase configuration for authenticated/server-side features
Install and validate:
pnpm install --frozen-lockfile
pnpm test
pnpm build
Run the frontend:
pnpm --filter @workspace/repo-finisher dev
Run the API:
pnpm --filter @workspace/api-server dev
Environment and secrets
Use .env.example as the canonical variable inventory.
Security rules:
VITE_* values are browser-visible. Never put service-role keys, provider secrets, GitHub tokens, signing secrets, encryption keys, or private keys in them.- Vercel frontend configuration requires the Supabase public URL/key and the API base URL or the source fallback.
- Contabo API and worker services require trusted Supabase credentials for server-side work.
PLAN_SIGNING_SECRET and SECRET_ENCRYPTION_KEY are backend-only.- GitHub OAuth Client ID/Secret belong in the Supabase GitHub auth provider configuration, not in browser-facing Vercel variables.
- User AI BYOK credentials must remain behind the trusted backend/Vault boundary.
CI and production release
A merge is not equivalent to a production release.
For production-impacting work verify separately:
- GitHub CI is green;
- the Vercel frontend deployment is healthy;
- the Contabo API deployment is healthy;
/api/healthz succeeds on the Contabo API;- the Contabo worker is running without crash/restart loops;
- required Supabase migrations/configuration are present;
- canonical DNS points at the intended Vercel/Contabo targets;
- authenticated user flows work end to end.
See docs/CONTABO_MIGRATION.md and docs/RELEASE-CHECKLIST.md.
Documentation
Start with docs/README.md.
Important files:
docs/CLOUD_RUN_MIGRATION.md is retained only as historical migration context.
