Arkyc

Open-source identity verification platform built on Arkstack (a runtime-agnostic TypeScript backend framework) and Arkormˣ (its ORM).

Arkyc lets applications verify users through document capture, OCR extraction, passive liveness detection, face matching, automated decisioning, manual review workflows, webhooks, and an SDK-powered embeddable widget — all multi-tenant from the ground up.

Status: early development. See ROADMAP.md for the phased plan. The monorepo skeleton (Phase 0) is in place; packages are stubs until their phase lands.

Monorepo layout

apps/
  api/          Arkstack API (public, client/widget, and dashboard surfaces)
  dashboard/    React + React Router + shadcn/ui management UI
  playground/   Example integration app

packages/
  types/        Shared domain types (contracts)
  core/         Decision engine, status transitions, scoring (pure logic)
  auth/         Password/token/API-key/client-token helpers
  permissions/  RBAC: resolve / authorize / sync default roles & permissions
  ocr/          Driver-based OCR (mock | external)
  liveness/     Driver-based passive liveness (mock | external)
  face-match/   Driver-based face matching (mock | external)
  webhooks/     Signing, verification, payload building
  sdk/          @arkyc/sdk — server + browser
  widget/       @arkyc/widget — embeddable verification flow

apps/api async work runs via the durable job queue and the `ark queue:work`
command (`ocr` + `biometric` roles) — see Phase 8 in ROADMAP.md.

docs/           Documentation

Requirements

• Node.js >= 20
• pnpm >= 10
• (optional, for local infra) Docker + Docker Compose — Postgres, Redis

Getting started

pnpm install

# Start local infra (Postgres + Redis)
docker compose up -d

# Copy environment template
cp .env.example .env

# Build / test / lint the whole workspace
pnpm build
pnpm test
pnpm lint

Running in Docker

docker compose up -d (above) starts infra only — Postgres, Redis and Soketi — for host-side development. To run the API itself in a container, use the opt-in app profile. The image (Dockerfile) mirrors the production build: it compiles the workspace and ships a slim, standalone artifact that runs the compiled server, applying migrations on startup.

# Build + start infra and the API (http://localhost:3100/health)
docker compose --profile app up -d --build

# Durable queue workers (only for QUEUE_CONNECTION=database|redis; the default
# `sync` runs jobs inline). Jobs span four named queues and `queue:work` takes one
# queue each, so the profile starts one worker per queue:
QUEUE_CONNECTION=database docker compose --profile app --profile worker up -d --build

APP_KEY (the at-rest encryption key) is minted on first boot with ark key:generate and persisted on the storage volume, so it stays stable across restarts with no setup. To pin it yourself, export it before up:

export APP_KEY=$(cd apps/api && pnpm -s ark key:generate --show)

The api/worker services read the compose service hostnames by default (postgres, redis, soketi); override DATABASE_URL, QUEUE_CONNECTION, REALTIME_TRANSPORT, etc. via your shell env or a root .env. See apps/api/.env.example for the full set of variables.

Workspace scripts

Scripts fan out across the workspace with pnpm -r (recursive, topological order).

Script	Description
pnpm build	Build every package/app in dependency order
pnpm dev	Run dev tasks across the workspace
pnpm test	Run Vitest across packages
pnpm lint	ESLint across the workspace
pnpm typecheck	tsc --noEmit across the workspace
pnpm format	Prettier write

This project is tested with BrowserStack

License

MIT