Documentation Index
Fetch the complete documentation index at: https://handbook.mhchq.ai/llms.txt
Use this file to discover all available pages before exploring further.
OpenInsure uses Woodpecker CI running on a self-managed Hetzner k3s cluster. GitHub is used exclusively as a version-control host. All automated quality enforcement, testing, security scanning, and deployment runs in Woodpecker. The Woodpecker dashboard is available at woodpecker.hk3.openinsure.dev.
Pipeline Overview
The .woodpecker/*.yaml files define the pipeline stages that form the full quality gate:
quick-checks → lint → test → quality-gate → security-scan
↘
(on tag) deploy
Pipeline: lint
Runs oxfmt --check . and biome check . for formatting and linting.
Pipeline: test
Runs the full quality gate:
Step: quick-checks
Fast, cheap validation that runs first to catch obvious problems:
| Step | Command | Purpose |
|---|
| Type check | tsp compile typespec/ | Validate TypeSpec API spec |
| Dead code | pnpm exec knip --reporter compact | Detect unused exports/deps |
| Workspace invariants | pnpm exec sherif | Verify pnpm workspace consistency |
| Unit smoke | pnpm --filter @openinsure/types test | Fast type-level sanity check |
Step: lint
Code quality and formatting:
| Step | Command | Purpose |
|---|
| Biome | biome check . | Lint + format all TypeScript/TSX |
| Oxlint | pnpm turbo oxlint | Secondary linter pass |
Step: test
Full test suite with coverage reporting:
Coverage is uploaded to Codecov after every green test run (requires CODECOV_TOKEN env var).
Step: quality-gate
Integration and end-to-end validation:
pnpm turbo build — verify all packages build cleanly- Database migration dry-run
- Release smoke tests (
scripts/release-smoke.sh)
- SLO guardrail checks (
scripts/check-slo-guardrails.sh)
Step: security-scan
Supply chain and dependency security:
| Step | Tool | Purpose |
|---|
| Audit | pnpm audit --audit-level=high | npm advisory database |
| Supply chain | Socket.dev CLI | Deep package provenance + threat intel |
SOCKET_SECURITY_API_KEY env var. Enabled scopes: diff-scans, full-scans, packages, dependencies, triage, threat-feed, security-policy, fixes.
Pipeline: deploy
.woodpecker/deploy.yaml has depends_on: [lint, test] — deploy runs only when both pipelines pass.
Step: deploy
Triggered on git tags (v*):
wrangler deploy # All workers in dependency order
oi-sys-auth → oi-sys-api → frontends.
Steps: deploy-finance-portal and deploy-compliance-portal
Each new portal has a dedicated deploy step that runs on master after build, test, lint, and typecheck pass. Both use path-based change detection — they only deploy when files in their respective apps/ directory or shared packages (auth-hooks, config, db, react-query, types, ui) change.
deploy-finance-portal:
steps:
- check-paths:
pattern: '^(apps/finance-portal/|packages/(auth-hooks|config|db|react-query|types|ui)/)'
- run: cd apps/finance-portal && npx opennextjs-cloudflare deploy -- --keep-vars
deploy-compliance-portal:
steps:
- check-paths:
pattern: '^(apps/compliance-portal/|packages/(auth-hooks|config|db|react-query|types|ui)/)'
- run: cd apps/compliance-portal && npx opennextjs-cloudflare deploy -- --keep-vars
--keep-vars so Cloudflare retains existing secrets (FINANCE_JWT_SECRET, COMPLIANCE_JWT_SECRET) set via wrangler secret put.
Knip — Dead Code Detection
Knip scans every workspace for unused exports, files, and dependencies.
pnpm knip
# or with compact output:
pnpm exec knip --reporter compact
knip.json at the repo root. It’s advisory in CI (|| true) — findings are surfaced as warnings, not failures, until the initial cleanup pass is complete.
What Knip catches:
- Exported functions/types that are never imported
- Dependencies declared in
package.json but never used
- Files that are not reachable from entry points
Sherif — Workspace Invariants
Sherif enforces consistency rules across pnpm workspaces — no syncpack, no custom scripts.
What Sherif enforces:
- All workspace packages that share a dependency use the same version
- No duplicate
package.json fields that conflict across workspaces
- Package names match their directory structure
Sherif was chosen over Syncpack because Syncpack v13 crashes on Node.js v25+. Sherif is zero-config for pnpm workspaces and works correctly on all Node.js versions.
OpenTofu — Infrastructure as Code
Azure AD resources (the Microsoft SSO app registration for oi-sys-auth) are managed with OpenTofu (the open-source Terraform fork) using the azuread provider.
infra/azure-auth/
├── main.tf # azuread_application, azuread_service_principal
├── variables.tf # tenant_id, client_id, redirect_uris
├── outputs.tf # application_id, client_secret
└── terraform.tfvars # NOT committed — contains Azure credentials
AzureADMyOrg), restricted to the mhcis.com tenant (ebd58a52-c818-4230-b150-348ae1e17975). Infrastructure changes are applied manually by a platform engineer with Azure Owner rights — there is no automated tofu apply in CI at this time.
# Plan changes
cd infra/azure-auth
tofu init
tofu plan
# Apply (requires Azure credentials in environment)
tofu apply
terraform.tfvars and any .tfstate files contain Azure client secrets and must never be committed to source control. The .gitignore at the repo root excludes *.tfvars and *.tfstate.
:::
Renovate — Automated Dependency Updates
Renovate runs weekly (Monday 06:00 ET) as a CronJob on Hetzner k3s and opens PRs for dependency updates. Requires RENOVATE_TOKEN env var (GitHub PAT with repo scope).
Auto-merge policy (configured in renovate.json):
| Update type | Policy |
|---|
| Patch versions | Auto-merge |
| Security vulnerabilities | Auto-merge |
| Next.js / React major | Manual review |
| Cloudflare Workers | Manual review |
| Drizzle ORM | Manual review |
| Turbo | Manual review |
| TanStack (all) | Grouped, manual review |
@radix-ui/* | Grouped, manual review |
@openinsure/* packages are excluded from Renovate.
EAS Mobile Deploy
The mobile deploy pipeline is defined in .woodpecker/mobile.yaml. It runs in parallel with the main pipeline: EAS Update on master push (when mobile-affecting paths change), EAS Build on mobile/v* git tags. It calls eas workflow:run .eas/workflows/production.yml which:
- Fingerprints native code for iOS and Android
- Checks if a compatible build already exists
- If native code changed → full EAS build + App Store / Play Store submit
- If only JS changed → OTA update to production channel (minutes, no store review)
Required env var: EXPO_TOKEN (set via woodpecker-cli repo secret add). Generate at expo.dev → Account Settings → Access Tokens.
Codecov — Coverage Tracking
Coverage reports are uploaded after every passing test run. Reports are uploaded from the test CI job using codecov-action.
To add coverage locally:
pnpm turbo test -- --coverage
CODECOV_TOKEN set in Woodpecker project secrets.
Socket.dev — Supply Chain Security
Socket.dev performs deep analysis of every npm package in the dependency graph — beyond the advisory database. It detects:
- Typosquatting — packages with names similar to popular ones
- Malicious code injection — packages that execute code at install time
- Dependency confusion — private package names published to the public registry
- Unmaintained packages — packages with no recent activity or abandoned by their author
- Protestware / env var exfiltration — behavioral analysis of install/postinstall scripts
Required Woodpecker Secrets
Secrets are managed via woodpecker-cli repo secret add. See CLAUDE.md for the full list.
| Variable | Purpose | Where to get |
|---|
cloudflare_api_token | Worker deployments | Cloudflare dashboard → API Tokens |
github_token | Repo write (tag step) | github.com/settings/tokens |
RENOVATE_TOKEN | GitHub PAT for Renovate PRs | github.com/settings/tokens |
CODECOV_TOKEN | Coverage upload | app.codecov.io |
SOCKET_SECURITY_API_KEY | Supply chain scan | socket.dev dashboard |
TURBO_TOKEN + TURBO_TEAM | Turbo remote cache | vercel.com/account/tokens |
DATABASE_URL | Migration jobs | PlanetScale dashboard (app.planetscale.com) |
JWT_SECRET | API test suite + admin/UW portal | Generate: openssl rand -hex 32 |
expo_token | EAS auth (mobile pipeline) | expo.dev → Account Settings → Access Tokens |
percy_token | Visual regression | Percy dashboard |
slack_webhook_url | Pipeline notifications | Slack app settings |
sentry_auth_token | Release tagging | Sentry → API Keys (project:releases scope) |
Note:
Sanctions API credentials are Worker secrets, not CI env vars. OPENSANCTIONS_API_URL and
OPENSANCTIONS_API_KEY are set via wrangler secret put on oi-sys-api. During CI,
OPENSANCTIONS_API_URL is intentionally absent — the static SDN fallback activates automatically
and all sanctions unit tests pass without a live endpoint.
Danger:
All CI credentials must be rotated before any production deployment. Dev credentials were set
during initial setup. See the PRE-LAUNCH REMINDER note in CLAUDE.md.
Local Quality Gate
Run the same checks locally before pushing:
# Type safety
pnpm exec tsc --noEmit
# Lint + format
biome check --write .
# Dead code audit
pnpm knip
# Workspace invariants
pnpm sherif
# Full test suite
pnpm turbo test
# Build verification
pnpm turbo build
Commit Conventions
Commits follow the Conventional Commits spec, enforced by commitlint:
feat(claims): add reserve change audit trail
fix(billing): correct invoice balance calculation
chore(deps): bump drizzle-orm to 0.45.1
api, billing, claims, portal).
Quickstart
Set up a local dev environment from scratch.
Architecture
Understand the edge/origin split and data flow.
