🛡️ Interdomestik V3
The #1 Consumer Protection & Claims Management Platform in the Balkans.
📋 Overview
Interdomestik is a subscription-based consumer protection service that helps members resolve disputes with companies, landlords, insurance providers, employers, and other entities. Version 3 (V3) represents our latest architectural evolution, featuring specific domain isolation, proxy-based routing, and enhanced multi-tenant security.
🛠️ Tech Stack
| Layer | Technology |
|---|
| Monorepo | Turborepo + pnpm (Workspaces) |
| Frontend | Next.js 15 (App Router) |
| Architecture | Domain-Driven Design (DDD) |
| Routing | Proxy-based (Middleware may exist but is not authoritative; proxy.ts is the source of truth) |
| UI | Custom Design System + Radix UI + Tailwind CSS |
| Database | Supabase (PostgreSQL) + Drizzle ORM |
| Auth | Supabase Auth (identity & persistence) + Better Auth via @interdomestik/shared-auth (orchestration, policies) |
| Payments | Paddle (V3 only) — Stripe references exist only in legacy code and are not part of the V3 runtime |
| i18n | next-intl (SQ, EN, MK, SR, DE, HR) |
📁 Project Structure
interdomestik/
├── apps/
│ └── web/ # Next.js 15 web application
│ ├── src/
│ │ ├── app/ # App Router pages
│ │ ├── proxy.ts # Primary routing & security logic
│ │ └── messages/ # Translation JSON files
│ └── e2e/ # Playwright tests & canonical routes
├── packages/
│ ├── domain-*/ # DDD Packages (claims, users, member, etc.)
│ ├── ui/ # Shared UI component library
│ ├── database/ # Drizzle schema & Supabase clients
│ └── shared-auth/ # Unified authentication logic
├── scripts/ # Automation & Security Guards
├── supabase/ # Migrations & Config
└── turbo.json # Turborepo configuration
🔐 Authentication Architecture (V3)
Authentication in Interdomestik V3 is intentionally abstracted and in transition.
- Supabase Auth remains the system of record for identities and sessions.
- better-auth is used as the active authentication orchestrator.
@interdomestik/shared-auth provides a provider-agnostic boundary layer, allowing the system to evolve without coupling business logic to a single auth vendor.
This design is deliberate and supports future authentication flexibility without disrupting the V3 pilot.
🚀 Getting Started
Prerequisites
- Node.js 20+
- pnpm 10+ (Required)
- Supabase CLI (for local DB)
- Docker (optional, for SonarQube/local services)
Installation
-
Clone the repository
git clone https://github.com/interdomestik/interdomestik.git
cd interdomestik
-
Install dependencies
pnpm install
-
Set up environment variables
cp .env.example .env.local
# Populate .env.local with Supabase, Better Auth, Paddle, Sentry, and tenant host values.
# V3 pilot billing uses Paddle only; do not add Stripe runtime credentials.
Development Boot
We use Boot Scripts to standardize startup:
# 🚀 Start Full Stack (Database + Next.js)
pnpm boot:dev
# 🧪 Prepare for E2E (Seeds database + setup)
pnpm boot:e2e
📍 Canonical Routes & Portals
V3 uses strict Canonical Routes. All access is governed by apps/web/src/proxy.ts.
| Role | Canonical Path | Description |
|---|
| Member | /member | Dashboard, Claims, Settings |
| Agent | /agent/members | Agent Portal & Member Mgmt |
| Staff | /staff/claims | Staff Operations Queue |
| Admin | /admin/overview | Executive Cockpit |
Note: Legacy middleware is no longer the primary routing authority. All canonical routing, access control, and tenant isolation are enforced in src/proxy.ts.
✅ Pilot Readiness & Quality Gates
V3 Pilot Scope
docs/plans/current-program.md is the sole authority for the current phase, priorities, and sequencing.
Do not infer the active slice from this README: M0→M5 is the conditional architecture-finalization authority when explicitly promoted, while Phase C remains the historical evidence ledger and its guardrails continue to apply.
Architecture, routing, clarity markers, and security guards are locked.
We enforce strict quality standards ("The Guard") for the V3 Pilot.
Verification (The Standard)
Before pushing any code, run the verifier:
pnpm pr:verify
Runs: repository contracts, release-gate tests, E2E contract checks, production lint-warning baseline, DB/RLS checks, i18n checks, coverage gate, the full E2E gate, and Web Smoke Tests. memory:precheck is separate opt-in advisory feedback. Use pnpm prod:ready:code for the Docker-free code gate; local E2E lanes run pnpm run doctor first.
For standalone pilot-launch checks when these results are not already covered by a successful
pr:verify for the same source, configuration, and environment, run:
pnpm check:e2e-contracts
pnpm lint:production-warnings
pnpm security:guard
pnpm e2e:gate
Security
We use an automated security guard to prevent sensitive leaks and unsafe patterns:
pnpm security:guard
Testing (Playwright + Vitest)
- Unit Tests:
pnpm test (Web) or pnpm test:unit:domains (Domains)
- E2E Gate:
pnpm e2e:gate (Strict quality gate)
- Clarity Markers: used in E2E tests to verify V3 surface readiness.
🚢 Release Readiness
The GitHub CD workflow builds separate staging and production Docker artifacts with explicit Supabase environment separation. Promotion is fail-closed: staging and production deploy jobs require environment-scoped deploy webhook secrets, then run health checks and release-gate evidence capture before production verification artifacts are retained. Production also runs pnpm release:evidence:check against docs/release/production-evidence.yaml; pending G01-G10 evidence keeps pnpm release:gate:prod fail-closed.
🌍 Internationalization
Supported Locales:
- 🇦🇱 SQ (Albanian) - Primary
- 🇬🇧 EN (English)
- 🇲🇰 MK (Macedonian)
- 🇷🇸 SR (Serbian)
- 🇩🇪 DE (German)
- 🇭🇷 HR (Croatian)
Updates to translations should be made in apps/web/src/messages/{locale}/.
📦 Database & Drizzle
We use Drizzle ORM for type-safe database interactions.
# Push schema changes (Local)
# Applies Supabase migrations with --local, not Drizzle schema push
pnpm db:push:local
# Open Drizzle Studio
pnpm db:studio
📄 License
Proprietary - All rights reserved. Interdomestik.
Built for the Balkans. 🛡️
