OpenKYC

OpenKYC is a self-hosted application for document collection and manual identity review. Operators create workflows, share private collection links, and review submitted documents from a tenant-scoped dashboard.

The system uses a React/TanStack Router frontend, an Express API, PostgreSQL with Drizzle, Redis, and private file storage. Docker Compose runs the application and its dependencies on a single server.

Start locally

Requires Node.js 22+ and Docker Compose v2.

git clone https://github.com/biomathcode/open-kyc.git
cd open-kyc
npm ci
npm run selfhost:init
docker compose up -d --build

Open localhost:3000, create an account, create an active workflow, and create a verification session. Share the generated secret collection link. Subjects upload PDFs or images, then submit them for manual review.

selfhost:init creates .env with random credentials and does not overwrite existing settings. PostgreSQL and Redis are private to the Docker network. The web app binds to loopback by default. The app, migrations, and persistent storage are included in Compose.

Included

• PostgreSQL/Drizzle persistence with tenant-scoped queries and versioned migrations.
• Better Auth email/password, optional SMTP magic links and password reset.
• Workflow creation, editing, activation, archival, and session creation.
• Expiring, secret-token document collection links; PDF/JPEG/PNG/WebP uploads up to 20 MB, 20 documents per session.
• Private document downloads, filename search, deletion, and manual review with audit history.
• Local disk, AWS S3, Google Cloud Storage, and Cloudflare R2 storage adapters.
• Redis upload tickets, API rate limits, and tenant-scoped live dashboard updates.
• Dashboard analytics, blocklist signals, public branding and privacy policy.
• Questionnaire authoring, publication, public responses, and response review.
• Developer API keys, REST endpoints, signed webhook events with retry and delivery status.
• Optional SMTP notifications and Firecrawl background search.
• npm workspaces: shared UI in packages/ui, contracts in packages/contracts.

Scope: Collected documents require manual review. OCR, face matching, automated identity/AML decisions, malware scanning, and RabbitMQ document workers are not implemented. Billing displays self-hosted usage; there is no hosted subscription requirement.

The frontend is now a Vite/TanStack Router SPA served by the Node API. This removes the former Convex/Netlify deployment coupling; server rendering of the marketing page is not included.

Documentation

• System architecture, data model, and collection flow
• Deployment, backups, custom domain and HTTPS
• Storage provider configuration
• Developer API and webhook protocol
• Import existing Convex data
• Original project README and v2 plan

Development and verification

After installing dependencies and initializing .env, start PostgreSQL and Redis, apply migrations, and run the development servers:

# Exposes development database ports only on loopback.
docker compose -f compose.yaml -f compose.dev.yaml up -d postgres redis
npm run db:migrate
npm run dev

Vite serves the frontend at http://localhost:3000 and proxies /api to the Node API at http://localhost:3001. Stop the Compose app with docker compose stop app before using the same port for Vite. The generated .env uses loopback database URLs for host development; Compose overrides these with internal service addresses.

Run checks in a separate terminal:

npm run build
npm test
# Against a running development deployment (localhost:3000 by default):
npm run test:integration
npx playwright install chromium
npm run test:e2e
# Against the development database and configured storage:
npx tsx tests/migration.ts

npm run build creates the production frontend and checks TypeScript. npm test runs access-control and storage unit tests. API integration tests exercise tenant isolation, uploads, submission, review, API keys, and public questionnaires; browser tests cover collection/review and workflow/questionnaire authoring. Set TEST_BASE_URL to test another development deployment.

Cloud provider tests use mocked SDK clients. Testing against your real buckets requires their credentials. API/browser integration tests create test accounts and fixtures; run them on a development deployment. The migration test checks explicit ownership, read-only validation, and repeatable imports.