Architecture Overview
Circuit KYC Network is a multi-tenant, event-driven platform for sharing verified identity data across financial institutions.
System Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ Partner Dashboard Python SDK TypeScript SDK REST API │
│ (React + Vite) (PyPI) (npm) (cURL/HTTP) │
└───────────┬─────────────┬─────────────────┬─────────────────┬───────────────┘
│ │ │ │
└─────────────┴────────┬────────┴─────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LOAD BALANCER (AWS NLB) │
│ api.circuitkyc.com (HTTPS/443) │
└───────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ KUBERNETES CLUSTER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ API SERVICE (FastAPI) │ │
│ │ 2+ replicas, port 8000 │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Middleware Stack: │ │ │
│ │ │ • CorrelationID → RateLimiter → UsageMetering → Auth │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Routers: │ │ │
│ │ │ • /api/v1/check-eligibility • /api/v1/issue │ │ │
│ │ │ • /api/v1/assess-risk • /api/v1/verify │ │ │
│ │ │ • /api/v1/ingest • /api/v1/claim-identity │ │ │
│ │ │ • /api/v1/onboarding/* • /api/v1/billing/* │ │ │
│ │ │ • /api/v1/webhooks/* • /api/v1/admin/* │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────┼───────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ WORKER SERVICE │ │ TRANSFORMER │ │ REDIS CLUSTER │ │
│ │ (Celery) │ │ SERVICE │ │ │ │
│ │ │ │ (Kafka Consumer) │ │ DB 0: Celery │ │
│ │ • Webhook │ │ │ │ DB 1: Rate Limit│ │
│ │ delivery │ │ • Processes │ │ │ │
│ │ • Sanctions │ │ bank.updates │ │ │ │
│ │ refresh │ │ • Blind indexing │ │ │ │
│ │ • Async tasks │ │ • DB writes │ │ │ │
│ └────────┬─────────┘ └────────┬─────────┘ └──────────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌──────────────────┐ │
│ │ │ REDPANDA │ │
│ │ │ (Kafka-compat) │ │
│ │ │ │ │
│ │ │ Topics: │ │
│ │ │ • bank.updates │ │
│ │ │ • audit.events │ │
│ │ └──────────────────┘ │
│ │ │
└───────────┼──────────────────────────────────────────────────────────────────┘
│
│
┌───────────┴──────────────────────────────────────────────────────────────────┐
│ EXTERNAL SERVICES │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ SUPABASE │ │ AWS SSM │ │ STRIPE │ │
│ │ (PostgreSQL) │ │ Parameter Store │ │ │ │
│ │ │ │ │ │ • Subscriptions │ │
│ │ • tenants │ │ • BLIND_INDEX_ │ │ • Payments │ │
│ │ • api_keys │ │ KEY │ │ • Invoices │ │
│ │ • identity_ │ │ • DATA_ENCRYPT_ │ │ • Webhooks │ │
│ │ registry │ │ ION_KEY │ │ │ │
│ │ • usage_logs │ │ • Secrets with │ │ │ │
│ │ • webhooks │ │ TTL caching │ │ │ │
│ │ • RLS policies │ │ │ │ │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Data Flow
1. Eligibility Check Flow
Partner App Circuit API Database
│ │ │
│ POST /check-eligibility │ │
│ {email, phone} │ │
│ ─────────────────────────► │ │
│ │ HMAC-SHA256 hash │
│ │ email → email_hash │
│ │ phone → phone_hash │
│ │ │
│ │ SELECT * FROM │
│ │ identity_registry │
│ │ WHERE email_hash=? │
│ │ ─────────────────────►│
│ │ │
│ │ ◄─────────────────────│
│ │ {is_verified, tier} │
│ │ │
│ ◄───────────────────────── │ │
│ {eligible: true, │ │
│ kyc_level: "standard", │ │
│ confidence: 0.87} │ │
2. Data Ingestion Flow
Partner App Circuit API Kafka Transformer Database
│ │ │ │ │
│ POST /ingest │ │ │ │
│ {records: [...]} │ │ │ │
│ ────────────────► │ │ │ │
│ │ Produce msg │ │ │
│ │ ──────────────►│ │ │
│ │ │ │ │
│ ◄──────────────── │ │ │ │
│ {batch_id, status │ │ │ │
│ "processing"} │ │ Consume │ │
│ │ │ ─────────────────► │
│ │ │ │ Blind index │
│ │ │ │ email → hash │
│ │ │ │ │
│ │ │ │ INSERT INTO │
│ │ │ │ identity_registry
│ │ │ │ ────────────────►
3. Webhook Delivery Flow
Circuit API Worker (Celery) Partner Endpoint
│ │ │
│ Event triggered │ │
│ (e.g., identity │ │
│ verified) │ │
│ │ │
│ Enqueue webhook │ │
│ ────────────────────►│ │
│ │ │
│ │ HMAC-SHA256 sign │
│ │ payload + timestamp │
│ │ │
│ │ POST /webhook │
│ │ X-Circuit-Signature │
│ │ ───────────────────────►
│ │ │
│ │ ◄───────────────────── │
│ │ 200 OK │
│ │ │
│ │ (on failure: retry │
│ │ with exponential │
│ │ backoff) │
Security Architecture
Authentication Layers
┌────────────────────────────────────────────────────────────┐
│ REQUEST │
└───────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ 1. API KEY VALIDATION │
│ • Header: X-API-Key │
│ • Hash comparison (SHA256) │
│ • Tenant lookup & status check │
└───────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ 2. RATE LIMITING │
│ • Sliding window algorithm │
│ • Per-tenant, per-endpoint limits │
│ • Tier-based multipliers │
└───────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ 3. CREDIT CHECK │
│ • Verify sufficient balance │
│ • Deduct credits post-request │
│ • HTTP 402 if insufficient │
└───────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ 4. BUSINESS LOGIC │
│ • Blind indexing (never store raw PII) │
│ • Encrypted document references │
│ • Ed25519 signed credentials │
└────────────────────────────────────────────────────────────┘
Cryptographic Operations
| Operation |
Algorithm |
Purpose |
| API Key Storage |
SHA256 |
One-way hash, never store plaintext |
| Blind Indexing |
HMAC-SHA256 |
Searchable PII without exposure |
| Data Encryption |
Fernet (AES-128) |
Encrypt document references |
| Credentials |
Ed25519 |
Sign verifiable credentials |
| Passwords |
Argon2id |
Hash partner passwords |
| Webhooks |
HMAC-SHA256 |
Sign webhook payloads |
Database Schema (Simplified)
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ tenants │ │ api_keys │ │ identity_registry│
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ id (PK) │───┐ │ id (PK) │ │ id (PK) │
│ name │ │ │ tenant_id (FK)──│───────│ phone_hash │
│ email │ │ │ key_hash │ │ email_hash │
│ password_hash │ │ │ environment │ │ is_verified │
│ tier │ │ │ is_active │ │ kyc_level │
│ credits │ │ │ last_used_at │ │ provider_id │
│ stripe_customer │ │ └─────────────────┘ └─────────────────┘
└─────────────────┘ │
│ │ ┌─────────────────┐ ┌─────────────────┐
│ │ │ usage_logs │ │ webhook_endpoints│
│ │ ├─────────────────┤ ├─────────────────┤
│ └──►│ tenant_id (FK) │ │ id (PK) │
│ │ api_key_id (FK) │ │ tenant_id (FK)──│───┐
│ │ endpoint │ │ url │ │
│ │ credits_used │ │ secret │ │
│ │ created_at │ │ events[] │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │credit_transactions│ │ webhook_deliveries│ │
│ ├─────────────────┤ ├─────────────────┤ │
└───────────►│ tenant_id (FK) │ │ endpoint_id (FK)│◄─────┘
│ amount │ │ event_type │
│ type │ │ status │
│ balance_after │ │ attempts │
└─────────────────┘ └─────────────────┘
Technology Stack
| Layer |
Technology |
Purpose |
| API |
FastAPI + Uvicorn |
Async Python web framework |
| Database |
Supabase (PostgreSQL) |
Managed Postgres with RLS |
| Cache |
Redis |
Rate limiting, Celery broker |
| Queue |
Celery |
Background task processing |
| Streaming |
Redpanda (Kafka) |
Event streaming, ingestion |
| Secrets |
AWS SSM |
Secure parameter storage |
| Auth |
JWT + API Keys |
Dual authentication |
| Crypto |
PyNaCl, Cryptography |
Ed25519, Fernet, HMAC |
| Payments |
Stripe |
Subscriptions, credits |
| Container |
Docker |
Application packaging |
| Orchestration |
Kubernetes (EKS) |
Production deployment |
| CI/CD |
GitHub Actions |
Build, test, deploy |
| Registry |
AWS ECR |
Container images |
Deployment Environments
| Environment |
URL |
Purpose |
| Production |
api.circuitkyc.com |
Live traffic |
| Staging |
staging-api.circuitkyc.com |
Pre-production testing |
| Development |
localhost:8000 |
Local development |