The Three-Repo Pattern
Every shared capability in the Kasha ecosystem follows a strict three-layer separation. Pure business logic lives in a versioned library with no I/O or database dependencies. A standalone middleware service owns its own PostgreSQL database and exposes a REST API. Platform consumers talk to the middleware through thin HTTP connector modules.
THREE-REPO MIDDLEWARE PATTERN ──────────────────────────────────────────────────────────────── Layer 1: Pure Logic (no DB, no I/O) ┌──────────────────────────────────────────────────────────────┐ │ @kashatech/lr-validation @kasha/kyc-service │ │ Tax rates, VAT rules, KycOrchestrator, │ │ scoring, classification providers, store interfaces │ └────────────────────┬─────────────────────────┬────────────────┘ | | npm install npm link | | Layer 2: Middleware Service (own DB, REST API) ┌────────────────────┴───────────────────────────┴────────────────┐ │ kasha-middleware-tax-service kasha-middleware-kyc-connector │ │ Port 3003/3004 · NestJS Port 3001/3002 · NestJS │ │ DB: tax_service DB: kyc_connector │ │ 12 REST endpoints 11 REST endpoints │ └────────────────────┬─────────────────────────┬────────────────┘ | | HTTP REST HTTP REST | | Layer 3: Platform Consumers (thin HTTP client) ┌────────────────────┴─────────────────────────┴────────────────┐ │ KashaCH MonoProject │ │ server/modules/tax-connector/ (thin proxy to tax middleware) │ │ server/modules/kyc-connector/ (thin proxy to KYC middleware) │ └──────────────────────────────────────────────────────────────┘
Deployed Middleware
Two middleware services are currently running in production. Both follow the three-repo pattern, own their databases, and serve REST APIs consumed by KashaCH MonoProject.
Capabilities
- Tax determination (country + canton level)
- VAT validation (format + VIES checks)
- Rate management with admin approval
- Rate watcher (weekly OECD/EU checks)
- Turnover monitoring (CHF 100k / 10k thresholds)
- Seller VAT registration awareness
- Tax rules engine with scoring
- ~200 country tax rate database
Capabilities
- Applicant management (create, sync, check)
- Sumsub integration (production provider)
- Mock provider auto-detection (dev)
- Webhook processing (HMAC validated)
- Risk matrix (14-factor scoring)
- Document management (28+ doc types)
- Proof of address verification
- Admin dashboard with pagination
Pure Logic Packages
Shared libraries contain provider-agnostic business logic with zero I/O dependencies. They can be consumed by middleware services, platform modules, CLIs, and test suites without any database or network configuration.
- Postal Codes (format validation)
- Billing Calculations (line totals, VAT)
- Tax Rates (~200 countries)
- VAT Validation (format + patterns)
- Tax Rules Engine
- Tax Registration Thresholds
- KycOrchestrator (workflow engine)
- SumsubProvider (production KYC)
- MockKycProvider (dev auto-approve)
- RiskMatrixCalculator (14-factor)
- Store interfaces (abstract contracts)
- Event system (lifecycle hooks)
Planned Extractions
The following domains are candidates for extraction into standalone middleware services. Each will follow the same three-repo pattern established by Tax and KYC.
Email Service
Multi-brand email delivery via SendGrid. Per-CSP branding, template engine, delivery tracking, bounce handling.
PlannedAML Screening
Sanctions and PEP screening via ComplyAdvantage. Continuous monitoring, match resolution, audit trail.
PlannedRegistry Connector
Company registry lookups across jurisdictions: Zefix (CH), Companies House (UK), VIES (EU VAT).
PlannedShipping Service
Multi-carrier shipping via Shippo. Label generation, tracking, rate comparison, return management.
PlannedPDF Generator
Document generation with worker pool. Per-tenant branding, template system. Worker pool already implemented.
PartialMore Domains
Payments, CRM, Notifications, Compliance — each extracted when two or more consumers need shared logic.
FutureDeployment & Networking
All middleware services deploy as Docker containers on a shared VPS, connected via a Docker bridge network. CI/CD runs through GitHub Actions with SSH deploy.
Port Allocation
| Service | Internal Port | External Port | Protocol |
|---|---|---|---|
| KYC Connector | 3001 |
3002 |
HTTP REST |
| Tax Middleware | 3003 |
3004 |
HTTP REST |
| Launch Readiness Hub | 80 |
3005 |
HTTP (nginx) |
Database Allocation
| Database | Owner Service | Engine | Entities |
|---|---|---|---|
kyc_connector |
KYC Connector | PostgreSQL (TypeORM) | 10 |
tax_service |
Tax Middleware | PostgreSQL | Multiple |
kashach |
MonoProject (Heidi) | PostgreSQL (Drizzle) | 40+ |
# Typical deploy flow (GitHub Actions) on: push to main steps: 1. SSH into VPS (letscodenow.app) 2. git pull origin main 3. docker compose build --no-cache 4. docker compose up -d 5. Health check: GET /healthz/ready (15s interval) 6. docker system prune -f # Docker network (all services share this) networks: kasha-dev-network: external: true # Services discover each other by container name # e.g., http://kyc-connector:3001/api/kyc
Documentation Links
Each middleware service and library maintains its own documentation. Standards are enforced through CLAUDE.md files at each repository level.
KYC Architecture Deep-Dive
Full case study of the middleware connector pattern with KYC as proof of concept. Includes API surface, data model, and deployment.
Launch Readiness Hub
Central project hub with POS concepts, GTM strategies, Luma AI, and platform architecture overview.
CLAUDE.md Standards
Coding standards enforced across all repos: module structure, single-writer pattern, type safety, billing math, and PR review checklist.
Extraction Principle
A capability is extracted into middleware when two or more platforms need the same business logic. The extraction always follows three steps: (1) Move pure logic into a versioned library with zero I/O dependencies. (2) Build a standalone NestJS service that owns its database and exposes REST endpoints. (3) Replace direct logic in consumers with thin HTTP connector modules. Each middleware service is independently deployable, testable, and scalable.