@serve.zone/dcrouter 13.18.0 → 13.19.0

package/readme.md

@@ -1,139 +1,44 @@
 # @serve.zone/dcrouter
 
-![](https://code.foss.global/serve.zone/docs/raw/branch/main/dcrouter.png)
+![dcrouter banner](https://code.foss.global/serve.zone/docs/raw/branch/main/dcrouter.png)
 
-**dcrouter: The all-in-one gateway for your datacenter.** 🚀
+`dcrouter` is a TypeScript control plane for running a serious multi-protocol edge or datacenter gateway from one process. It orchestrates HTTP/HTTPS and TCP routing through SmartProxy, email through smartmta, authoritative DNS and DNS-over-HTTPS, RADIUS, remote ingress tunnels, VPN access control, a typed Ops API, and a web dashboard.
 
-A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), DNS, RADIUS, VPN, and remote edge ingress — all from a single process. Designed for enterprises requiring robust traffic management, automatic TLS certificate provisioning, VPN-based access control, distributed edge networking, and enterprise-grade email infrastructure.
+It is built for operators who want one place to define routes, expose services, manage certificates, register domains and DNS providers, control VPN-only access, and inspect what is going on in production.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [Configuration Reference](#configuration-reference)
-- [HTTP/HTTPS & TCP/SNI Routing](#httphttps--tcpsni-routing)
-- [HTTP/3 (QUIC) Support](#http3-quic-support)
-- [Email System](#email-system)
-- [DNS Server](#dns-server)
-- [RADIUS Server](#radius-server)
-- [Remote Ingress](#remote-ingress)
-- [VPN Access Control](#vpn-access-control)
-- [Certificate Management](#certificate-management)
-- [Storage & Database](#storage--database)
-- [Security Features](#security-features)
-- [OpsServer Dashboard](#opsserver-dashboard)
-- [API Client](#api-client)
-- [API Reference](#api-reference)
-- [Sub-Modules](#sub-modules)
-- [Testing](#testing)
-- [Docker / OCI Container Deployment](#docker--oci-container-deployment)
-- [License and Legal Information](#license-and-legal-information)
-
-## Features
-
-### 🌐 Universal Traffic Router
-- **HTTP/HTTPS routing** with domain matching, path-based forwarding, and automatic TLS
-- **HTTP/3 (QUIC) enabled by default** — qualifying HTTPS routes automatically get QUIC/H3 support with zero configuration
-- **TCP/SNI proxy** for any protocol with TLS termination or passthrough
-- **DNS server** (Rust-powered via [SmartDNS](https://code.foss.global/push.rocks/smartdns)) with authoritative zones, dynamic record management, and DNS-over-HTTPS
-- **Multi-protocol support** on the same infrastructure via [SmartProxy](https://code.foss.global/push.rocks/smartproxy)
-
-### 📧 Complete Email Infrastructure (powered by [smartmta](https://code.foss.global/push.rocks/smartmta))
-- **Multi-domain SMTP server** on standard ports (25, 587, 465)
-- **Pattern-based email routing** with four action types: forward, process, deliver, reject
-- **DKIM signing & verification**, SPF, DMARC authentication stack
-- **Enterprise deliverability** with IP warmup schedules and sender reputation tracking
-- **Bounce handling** with automatic suppression lists
-- **Hierarchical rate limiting** — global, per-domain, per-sender
-
-### 🔒 Enterprise Security
-- **Automatic TLS certificates** via ACME (smartacme v9) with Cloudflare DNS-01 challenges
-- **Smart certificate scheduling** — per-domain deduplication, controlled parallelism, and account rate limiting handled automatically
-- **Per-domain exponential backoff** — failed provisioning attempts are tracked and backed off to avoid hammering ACME servers
-- **IP reputation checking** with caching and configurable thresholds
-- **Content scanning** for spam, viruses, and malicious attachments
-- **Security event logging** with structured audit trails
-
-### 📡 RADIUS Server
-- **MAC Authentication Bypass (MAB)** for network device authentication
-- **VLAN assignment** based on exact MAC, OUI prefix, or wildcard patterns
-- **RADIUS accounting** for session tracking, traffic metering, and billing
-- **Real-time management** via OpsServer API
-
-### 🌍 Remote Ingress (powered by [remoteingress](https://code.foss.global/serve.zone/remoteingress))
-- **Distributed edge networking** — accept traffic at remote edge nodes and tunnel it to the hub
-- **Edge registration CRUD** with secret-based authentication
-- **Auto-derived ports** — edges automatically pick up ports from routes tagged with `remoteIngress.enabled`
-- **Connection tokens** — generate a single opaque base64url token containing hubHost, hubPort, edgeId, and secret for easy edge provisioning
-- **Real-time status monitoring** — connected/disconnected state, public IP, active tunnels, heartbeat tracking
-- **OpsServer dashboard** with enable/disable, edit, secret regeneration, token copy, and delete actions
-
-### 🔐 VPN Access Control (powered by [smartvpn](https://code.foss.global/push.rocks/smartvpn))
-- **WireGuard + native transports** — standard WireGuard clients (iOS, Android, macOS, Windows, Linux) plus custom WebSocket/QUIC tunnels
-- **Route-level VPN gating** — mark any route with `vpn: { enabled: true }` to restrict access to VPN clients only, or `vpn: { enabled: true, mandatory: false }` to add VPN clients alongside existing access rules
-- **Tag-based access control** — assign `serverDefinedClientTags` to clients and restrict routes with `allowedServerDefinedClientTags`
-- **Constructor-defined clients** — pre-define VPN clients with tags in config for declarative, code-driven setup
-- **Rootless operation** — uses userspace NAT (smoltcp) with no root required
-- **Destination policy** — configurable `forceTarget`, `block`, or `allow` with allowList/blockList for granular traffic control
-- **Client management** — create, enable, disable, rotate keys, export WireGuard/SmartVPN configs via OpsServer API and dashboard
-- **IP-based enforcement** — VPN clients get IPs from a configurable subnet; SmartProxy enforces `ipAllowList` per route
-- **PROXY protocol v2** — the NAT engine sends PP v2 on outbound connections to preserve VPN client identity
-
-### ⚡ High Performance
-- **Rust-powered proxy engine** via SmartProxy for maximum throughput
-- **Rust-powered MTA engine** via smartmta (TypeScript + Rust hybrid) for reliable email delivery
-- **Rust-powered DNS engine** via SmartDNS for high-performance UDP and DNS-over-HTTPS
-- **Connection pooling** for outbound SMTP and backend services
-- **Socket-handler mode** — direct socket passing eliminates internal port hops
-- **Real-time metrics** via SmartMetrics (CPU, memory, connections, throughput)
-
-### 💾 Unified Database
-- **Two deployment modes**: embedded LocalSmartDb (zero-config) or external MongoDB
-- **15 document classes** covering routes, certs, VPN, RADIUS, security profiles, network targets, and caches
-- **Automatic TTL-based cleanup** for cached emails and IP reputation data
-- **Reusable references** — security profiles and network targets that propagate changes to all referencing routes
-
-### 🖥️ OpsServer Dashboard
-- **Web-based management interface** with real-time monitoring
-- **JWT authentication** with session persistence
-- **Live views** for connections, email queues, DNS queries, RADIUS sessions, certificates, remote ingress edges, VPN clients, and security events
-- **Domain-centric certificate overview** with backoff status and one-click reprovisioning
-- **Remote ingress management** with connection token generation and one-click copy
-- **Security profiles & network targets** — reusable security configurations and host:port targets with propagation to referencing routes
-- **Global warning banners** when database is disabled (management features unavailable)
-- **Read-only configuration display** for system overview
-- **Smart tab visibility handling** — auto-pauses all polling, WebSocket connections, and chart updates when the browser tab is hidden, preventing resource waste and tab freezing
-
-### 🔧 Programmatic API Client
-- **Object-oriented API** — resource classes (`Route`, `Certificate`, `ApiToken`, `RemoteIngress`, `Email`) with instance methods
-- **Builder pattern** — fluent `.setName().setMatch().save()` chains for creating routes, tokens, and edges
-- **Auto-injected auth** — JWT identity and API tokens included automatically in every request
-- **Dual auth modes** — login with credentials (JWT) or pass an API token for programmatic access
-- **Full coverage** — wraps every OpsServer endpoint with typed request/response pairs
+## Why dcrouter
+
+- 🌐 Run HTTP/HTTPS, TCP/SNI, email, DNS, RADIUS, VPN, and remote ingress from one orchestrated service.
+- 🔐 Keep certificates, routes, tokens, domains, and reusable route references in one management plane.
+- 🧠 Use system-managed routes for config-, email-, and DNS-derived traffic, plus API-managed routes for dynamic additions.
+- 📊 Get an Ops UI and TypedRequest API for monitoring, automation, and day-2 operations.
+- ⚡ Lean on Rust-backed data planes where it matters: proxying, DNS, email delivery, remote ingress, and VPN.
+
+## What It Covers
+
+| Area | What dcrouter does |
+| --- | --- |
+| HTTP / HTTPS / TCP | SmartProxy-based routing, TLS termination or passthrough, path/domain matching, optional HTTP/3 augmentation |
+| Email | smartmta-based SMTP ingress and delivery, route-based email handling, DKIM-aware domain support |
+| DNS | Authoritative DNS, DNS-over-HTTPS bootstrap routes, provider-backed and dcrouter-hosted domains and records |
+| Certificates | ACME-aware certificate management with dashboard and API support |
+| Access control | Source profiles, network targets, VPN-gated routes, API tokens, admin auth |
+| Network edge | Remote ingress hub for edge nodes tunneling traffic into the router |
+| Operations | Web dashboard, TypedRequest API, logs, metrics, health, route and token management |
 
 ## Installation
 
 ```bash
 pnpm add @serve.zone/dcrouter
-# or
-npm install @serve.zone/dcrouter
 ```
 
-### Prerequisites
-
-- **Node.js 20+** with ES module support
-- Valid domain with DNS control (for ACME certificate automation)
-- Cloudflare API token (for DNS-01 challenges) — optional
-
 ## Quick Start
 
-### Basic HTTP/HTTPS Router
+This is the smallest realistic setup: one HTTP route, embedded database enabled, and the Ops dashboard on port `3000`.
 
 ```typescript
 import { DcRouter } from '@serve.zone/dcrouter';
@@ -142,1533 +47,275 @@ const router = new DcRouter({
   smartProxyConfig: {
     routes: [
       {
-        name: 'web-app',
-        match: { domains: ['example.com', 'www.example.com'], ports: [443] },
-        action: {
-          type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 8080 }],
-          tls: { mode: 'terminate', certificate: 'auto' }
-        }
-      }
-    ],
-    acme: {
-      email: 'admin@example.com',
-      enabled: true,
-      useProduction: true
-    }
-  }
-});
-
-await router.start();
-```
-
-### Basic Email Server
-
-```typescript
-import { DcRouter } from '@serve.zone/dcrouter';
-
-const router = new DcRouter({
-  emailConfig: {
-    ports: [25, 587, 465],
-    hostname: 'mail.example.com',
-    domains: [
-      {
-        domain: 'example.com',
-        dnsMode: 'external-dns'
-      }
-    ],
-    routes: [
-      {
-        name: 'process-all',
-        match: { recipients: '*@example.com' },
-        action: {
-          type: 'process',
-          process: { scan: true, dkim: true, queue: 'normal' }
-        }
-      }
-    ]
-  }
-});
-
-await router.start();
-```
-
-### Full Stack with Dashboard
-
-```typescript
-import { DcRouter } from '@serve.zone/dcrouter';
-
-const router = new DcRouter({
-  // HTTP/HTTPS routing
-  smartProxyConfig: {
-    routes: [
-      {
-        name: 'website',
-        match: { domains: ['example.com'], ports: [443] },
+        name: 'app',
+        match: {
+          domains: ['app.example.com'],
+          ports: [80],
+        },
         action: {
           type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 80 }],
-          tls: { mode: 'terminate', certificate: 'auto' }
-        }
-      }
-    ],
-    acme: { email: 'ssl@example.com', enabled: true, useProduction: true }
-  },
-
-  // Email system (powered by smartmta)
-  emailConfig: {
-    ports: [25, 587, 465],
-    hostname: 'mail.example.com',
-    domains: [{ domain: 'example.com', dnsMode: 'external-dns' }],
-    routes: [
-      {
-        name: 'inbound-mail',
-        match: { recipients: '*@example.com' },
-        action: { type: 'process', process: { scan: true, dkim: true, queue: 'normal' } }
-      }
-    ]
-  },
-
-  // Authoritative DNS
-  dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
-  dnsScopes: ['example.com'],
-  publicIp: '203.0.113.1',
-  dnsRecords: [
-    { name: 'example.com', type: 'A', value: '203.0.113.1' },
-    { name: 'www.example.com', type: 'CNAME', value: 'example.com' }
-  ],
-
-  // RADIUS authentication
-  radiusConfig: {
-    authPort: 1812,
-    acctPort: 1813,
-    clients: [
-      { name: 'switch-1', ipRange: '192.168.1.0/24', secret: 'radius-secret', enabled: true }
+          targets: [{ host: '127.0.0.1', port: 3001 }],
+        },
+      },
     ],
-    vlanAssignment: {
-      defaultVlan: 100,
-      allowUnknownMacs: true,
-      mappings: [
-        { mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true },
-        { mac: 'aa:bb:cc', vlan: 20, enabled: true }  // OUI prefix
-      ]
-    },
-    accounting: { enabled: true, retentionDays: 30 }
   },
-
-  // Remote Ingress — edge nodes tunnel traffic to this hub
-  remoteIngressConfig: {
+  dbConfig: {
     enabled: true,
-    tunnelPort: 8443,
-    hubDomain: 'hub.example.com',
   },
-
-  // VPN — restrict sensitive routes to VPN clients
-  vpnConfig: {
-    enabled: true,
-    serverEndpoint: 'vpn.example.com',
-    clients: [
-      { clientId: 'dev-laptop', serverDefinedClientTags: ['engineering'] },
-    ],
-  },
-
-  // Unified database (embedded LocalSmartDb or external MongoDB)
-  dbConfig: { enabled: true },
-
-  // TLS & ACME
-  tls: { contactEmail: 'admin@example.com' },
-  dnsChallenge: { cloudflareApiKey: process.env.CLOUDFLARE_API_KEY }
+  opsServerPort: 3000,
 });
 
 await router.start();
-// OpsServer dashboard available at http://localhost:3000
-```
-
-## Architecture
-
-### System Overview
-
-```mermaid
-graph TB
-    subgraph "External Traffic"
-        HTTP[HTTP/HTTPS Clients]
-        SMTP[SMTP Clients]
-        TCP[TCP Clients]
-        DNS[DNS Queries]
-        RAD[RADIUS Clients]
-        EDGE[Edge Nodes]
-        VPN[VPN Clients]
-    end
-
-    subgraph "DcRouter Core"
-        DC[DcRouter Orchestrator]
-        SP[SmartProxy Engine<br/><i>Rust-powered</i>]
-        ES[smartmta Email Server<br/><i>TypeScript + Rust</i>]
-        DS[SmartDNS Server<br/><i>Rust-powered</i>]
-        RS[SmartRadius Server]
-        RI[RemoteIngress Hub<br/><i>Rust data plane</i>]
-        VS[SmartVPN Server<br/><i>Rust data plane</i>]
-        CM[Certificate Manager<br/><i>smartacme v9</i>]
-        OS[OpsServer Dashboard]
-        MM[Metrics Manager]
-        DB2[DcRouterDb<br/><i>smartdata + smartdb</i>]
-    end
-
-    subgraph "Backend Services"
-        WEB[Web Services]
-        MAIL[Mail Servers]
-        DB[Databases]
-        API[Internal APIs]
-    end
-
-    HTTP --> SP
-    TCP --> SP
-    SMTP --> ES
-    DNS --> DS
-    RAD --> RS
-    EDGE --> RI
-    VPN --> VS
-
-    DC --> SP
-    DC --> ES
-    DC --> DS
-    DC --> RS
-    DC --> RI
-    DC --> VS
-    DC --> CM
-    DC --> OS
-    DC --> MM
-    DC --> DB2
-
-    SP --> WEB
-    SP --> API
-    ES --> MAIL
-    ES --> DB
-    RI --> SP
-
-    CM -.-> SP
-    CM -.-> ES
-```
-
-### Core Components
-
-| Component | Package | Description |
-|-----------|---------|-------------|
-| **DcRouter** | `@serve.zone/dcrouter` | Central orchestrator — starts, stops, and coordinates all services |
-| **SmartProxy** | `@push.rocks/smartproxy` | High-performance HTTP/HTTPS and TCP/SNI proxy with route-based config (Rust engine) |
-| **UnifiedEmailServer** | `@push.rocks/smartmta` | Full SMTP server with pattern-based routing, DKIM, queue management (TypeScript + Rust) |
-| **DNS Server** | `@push.rocks/smartdns` | Authoritative DNS with dynamic records and DKIM TXT auto-generation (Rust engine) |
-| **SmartAcme** | `@push.rocks/smartacme` | ACME certificate management with per-domain dedup, concurrency control, and rate limiting |
-| **RADIUS Server** | `@push.rocks/smartradius` | Network authentication with MAB, VLAN assignment, and accounting |
-| **RemoteIngress** | `@serve.zone/remoteingress` | Distributed edge tunneling with Rust data plane and TS management |
-| **OpsServer** | `@api.global/typedserver` | Web dashboard + TypedRequest API for monitoring and management |
-| **MetricsManager** | `@push.rocks/smartmetrics` | Real-time metrics collection (CPU, memory, email, DNS, security) |
-| **DcRouterDb** | `@push.rocks/smartdata` + `@push.rocks/smartdb` | Unified database — embedded LocalSmartDb or external MongoDB for all persistence |
-
-### How It Works
-
-DcRouter acts purely as an **orchestrator** — it doesn't implement protocols itself. Instead, it wires together best-in-class packages for each protocol:
-
-1. **On `start()`**: DcRouter initializes OpsServer (default port 3000, configurable via `opsServerPort`), then spins up SmartProxy, smartmta, SmartDNS, SmartRadius, RemoteIngress, and SmartVPN based on which configs are provided. Services start in dependency order via `ServiceManager`.
-2. **During operation**: Each service handles its own protocol independently. SmartProxy uses a Rust-powered engine for maximum throughput. smartmta uses a hybrid TypeScript + Rust architecture for reliable email delivery. RemoteIngress runs a Rust data plane for edge tunnel networking. SmartVPN runs a Rust data plane for WireGuard and custom transports. SmartAcme v9 handles all certificate operations with built-in concurrency control and rate limiting.
-3. **On `stop()`**: All services are gracefully shut down in parallel, including cleanup of HTTP agents and DNS clients.
-
-### Rust-Powered Architecture
-
-DcRouter itself is a pure TypeScript orchestrator, but several of its core sub-components ship with **compiled Rust binaries** for performance-critical paths. At runtime each package detects the platform, unpacks the correct binary, and communicates with TypeScript over IPC/FFI — so you get the ergonomics of TypeScript with the throughput of native code.
-
-| Component | Rust Binary | What It Handles |
-|-----------|-------------|-----------------|
-| **SmartProxy** | `smartproxy-bin` | All TCP/TLS/HTTP proxy networking, NFTables integration, connection metrics |
-| **smartmta** | `mailer-bin` | SMTP server + client, DKIM/SPF/DMARC, content scanning, IP reputation |
-| **SmartDNS** | `smartdns-bin` | DNS server (UDP + DNS-over-HTTPS), DNSSEC, DNS client resolution |
-| **RemoteIngress** | `remoteingress-bin` | Edge tunnel data plane, multiplexed streams, heartbeat management |
-| **SmartVPN** | `smartvpn_daemon` | WireGuard (boringtun), Noise IK handshake, QUIC/WS transports, userspace NAT (smoltcp) |
-| **SmartRadius** | — | Pure TypeScript (no Rust component) |
-
-## Configuration Reference
-
-### `IDcRouterOptions`
-
-```typescript
-interface IDcRouterOptions {
-  // ── Base ───────────────────────────────────────────────────────
-  /** Base directory for all dcrouter data. Defaults to ~/.serve.zone/dcrouter */
-  baseDir?: string;
-
-  // ── Traffic Routing ────────────────────────────────────────────
-  /** SmartProxy config for HTTP/HTTPS and TCP/SNI routing */
-  smartProxyConfig?: ISmartProxyOptions;
-
-  // ── Email ──────────────────────────────────────────────────────
-  /** Unified email server configuration (smartmta) */
-  emailConfig?: IUnifiedEmailServerOptions;
-
-  /** Custom email port mapping overrides */
-  emailPortConfig?: {
-    portMapping?: Record<number, number>;
-    portSettings?: Record<number, any>;
-    receivedEmailsPath?: string;
-  };
-
-  // ── DNS ────────────────────────────────────────────────────────
-  /** Nameserver domains — get A records automatically */
-  dnsNsDomains?: string[];
-  /** Domains this server is authoritative for */
-  dnsScopes?: string[];
-  /** Public IP for NS A records */
-  publicIp?: string;
-  /** Ingress proxy IPs (hides real server IP) */
-  proxyIps?: string[];
-  /** Custom DNS records */
-  dnsRecords?: Array<{
-    name: string;
-    type: 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SOA';
-    value: string;
-    ttl?: number;
-    useIngressProxy?: boolean;
-  }>;
-
-  // ── RADIUS ─────────────────────────────────────────────────────
-  /** RADIUS server for network authentication */
-  radiusConfig?: {
-    authPort?: number;                   // default: 1812
-    acctPort?: number;                   // default: 1813
-    clients: IRadiusClient[];
-    vlanAssignment?: IVlanManagerConfig;
-    accounting?: { enabled: boolean; retentionDays?: number };
-  };
-
-  // ── Remote Ingress ─────────────────────────────────────────────
-  /** Remote Ingress hub for edge tunnel connections */
-  remoteIngressConfig?: {
-    enabled?: boolean;                   // default: false
-    tunnelPort?: number;                 // default: 8443
-    hubDomain?: string;                  // External hostname for connection tokens
-    tls?: {
-      certPath?: string;
-      keyPath?: string;
-    };
-  };
-
-  // ── VPN ───────────────────────────────────────────────────────
-  /** VPN server for route-level access control */
-  vpnConfig?: {
-    enabled?: boolean;                   // default: false
-    subnet?: string;                     // default: '10.8.0.0/24'
-    wgListenPort?: number;               // default: 51820
-    dns?: string[];                      // DNS servers pushed to VPN clients
-    serverEndpoint?: string;             // Hostname in generated client configs
-    clients?: Array<{                    // Pre-defined VPN clients
-      clientId: string;
-      serverDefinedClientTags?: string[];
-      description?: string;
-    }>;
-    destinationPolicy?: {                // Traffic routing policy
-      default: 'forceTarget' | 'block' | 'allow';
-      target?: string;                   // IP for forceTarget (default: '127.0.0.1')
-      allowList?: string[];              // Pass through directly
-      blockList?: string[];              // Always block (overrides allowList)
-    };
-  };
-
-  // ── HTTP/3 (QUIC) ────────────────────────────────────────────
-  /** HTTP/3 config — enabled by default on qualifying HTTPS routes */
-  http3?: {
-    enabled?: boolean;                   // default: true
-    quicSettings?: {
-      maxIdleTimeout?: number;           // default: 30000ms
-      maxConcurrentBidiStreams?: number;  // default: 100
-      maxConcurrentUniStreams?: number;   // default: 100
-      initialCongestionWindow?: number;
-    };
-    altSvc?: {
-      port?: number;                     // default: listening port
-      maxAge?: number;                   // default: 86400s
-    };
-    udpSettings?: {
-      sessionTimeout?: number;           // default: 60000ms
-      maxSessionsPerIP?: number;         // default: 1000
-      maxDatagramSize?: number;          // default: 65535
-    };
-  };
-
-  // ── OpsServer ────────────────────────────────────────────────
-  /** Port for the OpsServer web dashboard (default: 3000) */
-  opsServerPort?: number;
-
-  // ── TLS & Certificates ────────────────────────────────────────
-  tls?: {
-    contactEmail: string;
-    domain?: string;
-    certPath?: string;
-    keyPath?: string;
-  };
-  dnsChallenge?: { cloudflareApiKey?: string };
-
-  // ── Database ────────────────────────────────────────────────────
-  /** Unified database for all persistence (routes, certs, VPN, RADIUS, etc.) */
-  dbConfig?: {
-    enabled?: boolean;                   // default: true
-    mongoDbUrl?: string;                 // External MongoDB URL (omit for embedded LocalSmartDb)
-    storagePath?: string;                // default: '~/.serve.zone/dcrouter/tsmdb'
-    dbName?: string;                     // default: 'dcrouter'
-    cleanupIntervalHours?: number;       // default: 1
-    seedOnEmpty?: boolean;               // Seed default profiles/targets if DB is empty
-    seedData?: object;                   // Custom seed data
-  };
-}
-```
-
-## HTTP/HTTPS & TCP/SNI Routing
-
-DcRouter uses [SmartProxy](https://code.foss.global/push.rocks/smartproxy) for all HTTP/HTTPS and TCP/SNI routing. Routes are pattern-matched by domain, port, or both.
-
-### HTTPS with Auto-TLS
-
-```typescript
-{
-  name: 'api-gateway',
-  match: { domains: ['api.example.com'], ports: [443] },
-  action: {
-    type: 'forward',
-    targets: [{ host: '192.168.1.20', port: 8080 }],
-    tls: { mode: 'terminate', certificate: 'auto' }
-  }
-}
-```
-
-### TLS Passthrough (SNI Routing)
-
-```typescript
-{
-  name: 'secure-backend',
-  match: { domains: ['secure.example.com'], ports: [8443] },
-  action: {
-    type: 'forward',
-    targets: [{ host: '192.168.1.40', port: 8443 }],
-    tls: { mode: 'passthrough' }
-  }
-}
-```
-
-### TCP Port Range Forwarding
-
-```typescript
-{
-  name: 'database-cluster',
-  match: { ports: [{ from: 5432, to: 5439 }] },
-  action: {
-    type: 'forward',
-    targets: [{ host: '192.168.1.30', port: 'preserve' }],
-    security: { ipAllowList: ['192.168.1.0/24'] }
-  }
-}
 ```
 
-### HTTP Redirect
+Once the router is running, you can:
 
-```typescript
-{
-  name: 'http-to-https',
-  match: { ports: [80] },
-  action: { type: 'redirect', redirect: { to: 'https://{domain}{path}' } }
-}
-```
+- open the Ops dashboard on `http://localhost:3000`
+- inspect the route in the System Routes view
+- add API-managed routes through the dashboard or API client
+- enable DNS, email, VPN, remote ingress, or RADIUS by adding the corresponding config blocks
 
-## HTTP/3 (QUIC) Support
+## Mental Model
 
-DcRouter ships with **HTTP/3 enabled by default** 🚀. All qualifying HTTPS routes on port 443 are automatically augmented with QUIC/H3 configuration — no extra setup needed. Under the hood, SmartProxy's native HTTP/3 support (via `IRouteQuic`) handles QUIC transport, Alt-Svc advertisement, and HTTP/3 negotiation.
+`dcrouter` is not a toy reverse proxy with a few side features. It is an orchestrator that wires multiple specialized services into one management plane.
 
-### How It Works
+| Layer | Responsibility |
+| --- | --- |
+| `DcRouter` | Startup order, shutdown, service wiring, configuration assembly, route hydration |
+| SmartProxy | HTTP/HTTPS, TCP/SNI, TLS, HTTP/3-capable route execution |
+| smartmta | SMTP ingress, queueing, DKIM-aware email processing and delivery |
+| SmartDNS | Authoritative DNS and DoH request handling |
+| smartradius | Network authentication, VLAN assignment, accounting |
+| remoteingress | Edge tunnel registrations and runtime forwarding into the hub |
+| smartvpn | VPN server and client access mediation for protected routes |
+| OpsServer + dashboard | Typed API and browser UI for operations |
+| smartdata-backed DB | Persistent routes, tokens, domains, records, profiles, cert metadata, caches |
 
-When DcRouter assembles routes in `setupSmartProxy()`, it automatically augments qualifying routes with:
-- `match.transport: 'all'` — listen on both TCP (HTTP/1.1 + HTTP/2) and UDP (QUIC/HTTP/3) on the same port
-- `action.udp.quic` — QUIC configuration with `enableHttp3: true` and `altSvcMaxAge: 86400`
+## Route Model
 
-Browsers that support HTTP/3 will discover it via the `Alt-Svc` header on initial TCP responses, then upgrade to QUIC for subsequent requests.
+Routes fall into two ownership classes:
 
-### What Gets Augmented
+| Route kind | Origin | Ownership | What users can do |
+| --- | --- | --- | --- |
+| System routes | `config`, `email`, `dns` | Derived from config or runtime-managed subsystems | View and toggle only |
+| API routes | `api` | Created through route-management API | Create, edit, delete, toggle |
 
-A route qualifies for HTTP/3 augmentation when **all** of these are true:
-- Port includes **443** (single number, array, or range)
-- Action type is **`forward`** (not `socket-handler`)
-- **TLS is enabled** (passthrough, terminate, or terminate-and-reencrypt)
-- Route is **not** an email route (ports 25/587/465)
-- Route doesn't already have `transport: 'all'` or existing `udp.quic` config
+Important details:
 
-### Zero-Config (Default Behavior)
+- system routes are persisted with a stable `systemKey`
+- config-, email-, and DNS-derived routes show up in the System Routes view
+- DoH routes are persisted as system-route templates and get their live socket handlers attached at apply time
+- system routes are managed by the system, not edited directly by operators
 
-```typescript
-// HTTP/3 is ON by default — this route automatically gets QUIC/H3:
-const router = new DcRouter({
-  smartProxyConfig: {
-    routes: [{
-      name: 'web-app',
-      match: { domains: ['example.com'], ports: [443] },
-      action: {
-        type: 'forward',
-        targets: [{ host: '192.168.1.10', port: 8080 }],
-        tls: { mode: 'terminate', certificate: 'auto' }
-      }
-    }]
-  }
-});
-```
+## Core Features
 
-### Per-Route Opt-Out
+### Traffic Routing
 
-Disable HTTP/3 on a specific route using `action.options.http3`:
+- Domain-, port-, and path-based SmartProxy routes
+- HTTP/HTTPS reverse proxying and generic TCP/SNI forwarding
+- Optional HTTP/3 augmentation for qualifying HTTPS routes
+- Reusable source profiles and network targets for route composition
+- Remote ingress aware routing for edge-delivered traffic
 
-```typescript
-{
-  name: 'legacy-app',
-  match: { domains: ['legacy.example.com'], ports: [443] },
-  action: {
-    type: 'forward',
-    targets: [{ host: '192.168.1.50', port: 8080 }],
-    tls: { mode: 'terminate', certificate: 'auto' },
-    options: { http3: false }  // ← This route stays TCP-only
-  }
-}
-```
+### Email
 
-### Global Opt-Out
+- smartmta-based inbound email handling
+- Route-based mail actions such as forward, process, deliver, reject
+- DKIM-aware domain handling and DNS record generation support
+- Email-domain management through the Ops API and UI
+- Queue, resend, failure, and delivery inspection through the dashboard and API
 
-Disable HTTP/3 across all routes:
+### DNS
 
-```typescript
-const router = new DcRouter({
-  http3: { enabled: false },
-  smartProxyConfig: { routes: [/* ... */] }
-});
-```
+- Authoritative scopes via `dnsScopes`
+- Bootstrap nameserver domains via `dnsNsDomains`
+- DNS-over-HTTPS endpoints for `/dns-query` and `/resolve`
+- Managed domains, managed records, and provider-backed DNS integrations
+- Internal email DNS record generation for `internal-dns` email domains
 
-### Custom QUIC Settings
+### Certificates and ACME
 
-Fine-tune QUIC parameters globally:
+- Certificate overview and operations through OpsServer
+- Import, export, delete, and reprovision flows
+- DB-backed ACME configuration management
+- Integration with managed DNS for certificate provisioning flows
+- Routes can declare `certificate: 'auto'`, but actual automated issuance depends on ACME being configured in the management plane
 
-```typescript
-const router = new DcRouter({
-  http3: {
-    quicSettings: {
-      maxIdleTimeout: 60000,          // 60s idle timeout
-      maxConcurrentBidiStreams: 200,   // More parallel streams
-      maxConcurrentUniStreams: 50,
-    },
-    altSvc: {
-      maxAge: 3600,                   // 1 hour Alt-Svc cache
-    },
-    udpSettings: {
-      sessionTimeout: 120000,         // 2 min UDP session timeout
-      maxSessionsPerIP: 500,
-    }
-  },
-  smartProxyConfig: { routes: [/* ... */] }
-});
-```
+### VPN, RADIUS, and Remote Ingress
 
-### Programmatic Routes
+- VPN-gated routes with target-profile-based access matching
+- WireGuard-oriented VPN management with dcrouter-side client lifecycle support
+- RADIUS MAB, VLAN assignment, and accounting
+- Remote ingress hub for edge nodes tunneling traffic into central routes
 
-Routes added at runtime via the Route Management API also get HTTP/3 augmentation automatically — the `RouteConfigManager` applies the same augmentation logic when merging programmatic routes.
+### Operations Plane
 
-## Email System
+- Web dashboard with overview, network, routes, access, security, domains, certificates, logs, and email views
+- TypedRequest API for automation and external control
+- API tokens with scoped access
+- Metrics, health, logs, and per-feature operational views
 
-The email system is powered by [`@push.rocks/smartmta`](https://code.foss.global/push.rocks/smartmta), a TypeScript + Rust hybrid MTA. DcRouter configures and orchestrates smartmta's **UnifiedEmailServer**, which handles SMTP sessions, route matching, delivery queuing, DKIM signing, and all email processing.
+## Configuration Overview
 
-### Email Domain Configuration
+The main entry point is `IDcRouterOptions`.
 
-Domains define _infrastructure_ — how DNS and DKIM are handled for each domain:
+| Option | Purpose |
+| --- | --- |
+| `smartProxyConfig` | Main HTTP/HTTPS and TCP/SNI routing configuration |
+| `emailConfig` | smartmta server config and email routes |
+| `emailPortConfig` | External-to-internal email port mapping and email storage path tuning |
+| `dnsNsDomains` | Nameserver hostnames used for NS bootstrap and DoH routes |
+| `dnsScopes` | Authoritative DNS zones managed by dcrouter |
+| `dnsRecords` | Static constructor-defined records |
+| `publicIp` / `proxyIps` | DNS A-record exposure strategy |
+| `dbConfig` | Embedded or external Mongo-backed persistence and seeding |
+| `radiusConfig` | RADIUS authentication, VLAN, and accounting setup |
+| `remoteIngressConfig` | Edge tunnel hub setup |
+| `vpnConfig` | VPN server and client access configuration |
+| `http3` | Global HTTP/3 behavior for qualifying routes |
+| `opsServerPort` | Dashboard and TypedRequest API port |
 
-#### Forward Mode
-Simple forwarding without local DNS management:
-```typescript
-{
-  domain: 'forwarded.com',
-  dnsMode: 'forward',
-  dns: { forward: { skipDnsValidation: true, targetDomain: 'mail.target.com' } }
-}
-```
+## Example: Enabling DNS, Email, and VPN
 
-#### Internal DNS Mode
-Uses DcRouter's built-in DNS server (requires `dnsNsDomains` + `dnsScopes`):
 ```typescript
-{
-  domain: 'mail.example.com',
-  dnsMode: 'internal-dns',
-  dns: { internal: { mxPriority: 10, ttl: 3600 } },
-  dkim: { selector: 'mail2024', keySize: 2048, rotateKeys: true, rotationInterval: 90 }
-}
-```
-
-#### External DNS Mode
-Uses existing DNS infrastructure with validation:
-```typescript
-{
-  domain: 'mail.external.com',
-  dnsMode: 'external-dns',
-  dns: { external: { requiredRecords: ['MX', 'SPF', 'DKIM', 'DMARC'] } },
-  rateLimits: {
-    inbound: { messagesPerMinute: 100, connectionsPerIp: 10 },
-    outbound: { messagesPerMinute: 200 }
-  }
-}
-```
-
-### Email Route Actions
-
-Routes define _behavior_ — what happens when an email matches:
-
-#### Forward 📤
-Routes emails to an external SMTP server:
-```typescript
-{
-  name: 'forward-to-internal',
-  match: { recipients: '*@company.com' },
-  action: {
-    type: 'forward',
-    forward: {
-      host: 'internal-mail.company.com',
-      port: 25,
-      auth: { user: 'relay-user', pass: 'relay-pass' },
-      addHeaders: { 'X-Forwarded-By': 'dcrouter' }
-    }
-  }
-}
-```
-
-#### Process ⚙️
-Full MTA processing with content scanning and delivery queues:
-```typescript
-{
-  name: 'process-notifications',
-  match: { recipients: '*@notifications.company.com' },
-  action: {
-    type: 'process',
-    process: { scan: true, dkim: true, queue: 'priority' }
-  }
-}
-```
-
-#### Deliver 📥
-Local mailbox delivery:
-```typescript
-{
-  name: 'deliver-local',
-  match: { recipients: '*@local.company.com' },
-  action: { type: 'deliver' }
-}
-```
-
-#### Reject 🚫
-Reject with custom SMTP response code:
-```typescript
-{
-  name: 'reject-spam-domain',
-  match: { senders: '*@spam-domain.com', sizeRange: { min: 1000000 } },
-  action: {
-    type: 'reject',
-    reject: { code: 550, message: 'Message rejected due to policy' }
-  }
-}
-```
-
-### Route Matching
-
-Routes support powerful matching criteria:
-
-```typescript
-// Recipient patterns
-match: { recipients: '*@example.com' }           // All addresses at domain
-match: { recipients: 'admin@*' }                 // "admin" at any domain
-match: { senders: ['*@trusted.com', '*@vip.com'] } // Multiple sender patterns
-
-// IP-based matching (CIDR)
-match: { clientIp: '192.168.0.0/16' }
-match: { clientIp: ['10.0.0.0/8', '172.16.0.0/12'] }
-
-// Authentication state
-match: { authenticated: true }
-
-// Header matching
-match: { headers: { 'X-Priority': 'high', 'Subject': /urgent|emergency/i } }
-
-// Size and content
-match: { sizeRange: { min: 1000, max: 5000000 }, hasAttachments: true }
-match: { subject: /invoice|receipt/i }
-```
-
-### Email Security Stack
-
-- **DKIM** — Automatic key generation, signing, and rotation for all domains
-- **SPF** — Sender Policy Framework verification on inbound mail
-- **DMARC** — Domain-based Message Authentication verification
-- **IP Reputation** — Real-time IP reputation checking with caching
-- **Content Scanning** — Spam, virus, and attachment scanning
-- **Rate Limiting** — Hierarchical limits (global → domain → sender)
-- **Bounce Management** — Automatic bounce detection and suppression lists
-
-### Email Deliverability
-
-- **IP Warmup Manager** — Multi-stage warmup schedules for new IPs
-- **Sender Reputation Monitor** — Per-domain reputation tracking and scoring
-- **Connection Pooling** — Pooled outbound SMTP connections per destination
-
-## DNS Server
-
-DcRouter includes an authoritative DNS server built on [smartdns](https://code.foss.global/push.rocks/smartdns). It handles standard UDP DNS on port 53 and DNS-over-HTTPS via SmartProxy socket handler.
-
-### Enabling DNS
-
-DNS is activated when both `dnsNsDomains` and `dnsScopes` are configured:
-
-```typescript
-const router = new DcRouter({
-  dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
-  dnsScopes: ['example.com'],
-  publicIp: '203.0.113.1',
-  dnsRecords: [
-    { name: 'example.com', type: 'A', value: '203.0.113.1' },
-    { name: 'www.example.com', type: 'CNAME', value: 'example.com' },
-    { name: 'example.com', type: 'MX', value: '10:mail.example.com' },
-    { name: 'example.com', type: 'TXT', value: 'v=spf1 a mx ~all' }
-  ]
-});
-```
-
-### Automatic DNS Records
-
-DcRouter auto-generates:
-- **NS records** for all domains in `dnsScopes`
-- **SOA records** for authoritative zones
-- **A records** for nameserver domains (`dnsNsDomains`)
-- **MX, SPF, DKIM, DMARC records** for email domains with `internal-dns` mode
-- **ACME challenge records** for certificate provisioning
-
-### Ingress Proxy Support
-
-When `proxyIps` is configured, A records with `useIngressProxy: true` (default) will use the proxy IP instead of the real server IP — hiding your origin:
-
-```typescript
-{
-  proxyIps: ['198.51.100.1', '198.51.100.2'],
-  dnsRecords: [
-    { name: 'example.com', type: 'A', value: '203.0.113.1' },  // Will resolve to 198.51.100.1
-    { name: 'ns1.example.com', type: 'A', value: '203.0.113.1', useIngressProxy: false }  // Stays real IP
-  ]
-}
-```
-
-## RADIUS Server
-
-DcRouter includes a RADIUS server for network access control, built on [smartradius](https://code.foss.global/push.rocks/smartradius).
-
-### Configuration
-
-```typescript
-const router = new DcRouter({
-  radiusConfig: {
-    authPort: 1812,
-    acctPort: 1813,
-    clients: [
-      {
-        name: 'core-switch',
-        ipRange: '192.168.1.0/24',
-        secret: 'shared-secret',
-        enabled: true
-      }
-    ],
-    vlanAssignment: {
-      defaultVlan: 100,
-      allowUnknownMacs: true,
-      mappings: [
-        { mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true },   // Exact MAC
-        { mac: 'aa:bb:cc', vlan: 20, enabled: true },             // OUI prefix
-      ]
-    },
-    accounting: {
-      enabled: true,
-      retentionDays: 30
-    }
-  }
-});
-```
-
-### Components
-
-| Component | Purpose |
-|-----------|---------|
-| **RadiusServer** | Main RADIUS server handling auth + accounting requests |
-| **VlanManager** | MAC-to-VLAN mapping with exact, OUI, and wildcard patterns |
-| **AccountingManager** | Session tracking, traffic metering, start/stop/interim updates |
-
-### OpsServer API
-
-RADIUS is fully manageable at runtime via the OpsServer API:
-- Client management (add/remove/list NAS devices)
-- VLAN mapping CRUD operations
-- Session monitoring and forced disconnects
-- Accounting summaries and statistics
-
-## Remote Ingress
-
-DcRouter can act as a **hub** for distributed edge nodes using [`@serve.zone/remoteingress`](https://code.foss.global/serve.zone/remoteingress). Edge nodes accept incoming traffic at remote locations and tunnel it back to the hub over a single multiplexed connection. This is ideal for scenarios where you need to accept traffic at multiple geographic locations but process it centrally.
-
-### Enabling Remote Ingress
+import { DcRouter } from '@serve.zone/dcrouter';
 
-```typescript
 const router = new DcRouter({
-  remoteIngressConfig: {
-    enabled: true,
-    tunnelPort: 8443,
-    hubDomain: 'hub.example.com',  // Embedded in connection tokens
-  },
-  // Routes tagged with remoteIngress are auto-derived to edge listen ports
   smartProxyConfig: {
     routes: [
       {
-        name: 'web-via-edge',
-        match: { domains: ['app.example.com'], ports: [443] },
-        action: {
-          type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 8080 }],
-          tls: { mode: 'terminate', certificate: 'auto' }
+        name: 'web-app',
+        match: {
+          domains: ['app.example.com'],
+          ports: [443],
         },
-        remoteIngress: { enabled: true }  // Edges will listen on port 443
-      }
-    ]
-  }
-});
-
-await router.start();
-```
-
-### Edge Registration
-
-Edges are registered via the OpsServer API (or dashboard UI). Each edge gets a unique ID and secret:
-
-```typescript
-// Via TypedRequest API
-const createReq = new TypedRequest<IReq_CreateRemoteIngress>(
-  'https://hub:3000/typedrequest', 'createRemoteIngress'
-);
-const { edge } = await createReq.fire({
-  identity,
-  name: 'edge-nyc-01',
-  autoDerivePorts: true,
-  tags: ['us-east'],
-});
-// edge.secret is returned only on creation — save it!
-```
-
-### Connection Tokens 🔑
-
-Instead of configuring edges with four separate values (hubHost, hubPort, edgeId, secret), DcRouter can generate a single **connection token** — an opaque base64url string that encodes everything:
-
-```typescript
-// Via TypedRequest API
-const tokenReq = new TypedRequest<IReq_GetRemoteIngressConnectionToken>(
-  'https://hub:3000/typedrequest', 'getRemoteIngressConnectionToken'
-);
-const { token } = await tokenReq.fire({ identity, edgeId: 'edge-uuid' });
-// token = "eyJoIjoiaHViLmV4YW1wbGUuY29tIiwicCI6ODQ0MywiZSI6I..."
-
-// On the edge side, just pass the token:
-const edge = new RemoteIngressEdge({ token });
-await edge.start();
-```
-
-The token is generated using `remoteingress.encodeConnectionToken()` and contains `{ hubHost, hubPort, edgeId, secret }`. The `hubHost` comes from `remoteIngressConfig.hubDomain` (or can be overridden per-request).
-
-In the OpsServer dashboard, click **"Copy Token"** on any edge row to copy the connection token to your clipboard.
-
-### Auto-Derived Ports
-
-When routes have `remoteIngress: { enabled: true }`, edges with `autoDerivePorts: true` (default) automatically pick up those routes' ports. You can also use `edgeFilter` to restrict which edges get which ports:
-
-```typescript
-{
-  name: 'web-route',
-  match: { ports: [443] },
-  action: { /* ... */ },
-  remoteIngress: {
-    enabled: true,
-    edgeFilter: ['us-east', 'edge-uuid-123']  // Only edges with matching id or tags
-  }
-}
-```
-
-### Dashboard Actions
-
-The OpsServer Remote Ingress view provides:
-
-| Action | Description |
-|--------|-------------|
-| **Create Edge Node** | Register a new edge with name, ports, tags |
-| **Enable / Disable** | Toggle an edge on or off |
-| **Edit** | Modify name, manual ports, auto-derive setting, tags |
-| **Regenerate Secret** | Issue a new secret (invalidates the old one) |
-| **Copy Token** | Generate and copy a base64url connection token to clipboard |
-| **Delete** | Remove the edge registration |
-
-## VPN Access Control
-
-DcRouter integrates [`@push.rocks/smartvpn`](https://code.foss.global/push.rocks/smartvpn) to provide VPN-based route access control. VPN clients connect via standard WireGuard or native WebSocket/QUIC transports, receive an IP from a configurable subnet, and can then access routes that are restricted to VPN-only traffic.
-
-### How It Works
-
-1. **SmartVPN daemon** runs inside dcrouter with a Rust data plane (WireGuard via `boringtun`, custom protocol via Noise IK)
-2. Clients connect and get assigned an IP from the VPN subnet (e.g. `10.8.0.0/24`)
-3. **Smart split tunnel** — generated WireGuard configs auto-include the VPN subnet plus DNS-resolved IPs of VPN-gated domains. Domains from routes with `vpn.enabled` are resolved at config generation time, so clients route only the necessary traffic through the tunnel
-4. Routes with `vpn: { enabled: true }` get `security.ipAllowList` dynamically injected (re-computed on every client change). With `mandatory: true` (default), the allowlist is replaced; with `mandatory: false`, VPN IPs are appended to existing rules
-5. When `allowedServerDefinedClientTags` is set, only matching client IPs are injected (not the whole subnet)
-6. SmartProxy enforces the allowlist — only authorized VPN clients can access protected routes
-7. All VPN traffic is forced through SmartProxy via userspace NAT with PROXY protocol v2 — no root required
-
-### Destination Policy
-
-By default, VPN client traffic is redirected to localhost (SmartProxy) via `forceTarget`. You can customize this with a destination policy:
-
-```typescript
-// Default: all traffic → SmartProxy
-destinationPolicy: { default: 'forceTarget', target: '127.0.0.1' }
-
-// Allow direct access to a backend subnet
-destinationPolicy: {
-  default: 'forceTarget',
-  target: '127.0.0.1',
-  allowList: ['192.168.190.*'],     // direct access to this subnet
-  blockList: ['192.168.190.1'],     // except the gateway
-}
-
-// Block everything except specific IPs
-destinationPolicy: {
-  default: 'block',
-  allowList: ['10.0.0.*', '192.168.1.*'],
-}
-```
-
-### Configuration
-
-```typescript
-const router = new DcRouter({
-  vpnConfig: {
-    enabled: true,
-    subnet: '10.8.0.0/24',            // VPN client IP pool (default)
-    wgListenPort: 51820,               // WireGuard UDP port (default)
-    serverEndpoint: 'vpn.example.com', // Hostname in generated client configs
-    dns: ['1.1.1.1', '8.8.8.8'],      // DNS servers pushed to clients
-
-    // Pre-define VPN clients with server-defined tags
-    clients: [
-      { clientId: 'alice-laptop', serverDefinedClientTags: ['engineering'], description: 'Dev laptop' },
-      { clientId: 'bob-phone', serverDefinedClientTags: ['engineering', 'mobile'] },
-      { clientId: 'carol-desktop', serverDefinedClientTags: ['finance'] },
-    ],
-
-    // Optional: customize destination policy (default: forceTarget → localhost)
-    // destinationPolicy: { default: 'forceTarget', target: '127.0.0.1', allowList: ['192.168.1.*'] },
-  },
-  smartProxyConfig: {
-    routes: [
-      // 🔐 VPN-only: any VPN client can access
-      {
-        name: 'internal-app',
-        match: { domains: ['internal.example.com'], ports: [443] },
         action: {
           type: 'forward',
-          targets: [{ host: '192.168.1.50', port: 8080 }],
+          targets: [{ host: '127.0.0.1', port: 8080 }],
           tls: { mode: 'terminate', certificate: 'auto' },
         },
-        vpn: { enabled: true },
       },
-      // 🔐 VPN + tag-restricted: only 'engineering' tagged clients
+    ],
+  },
+  emailConfig: {
+    hostname: 'mail.example.com',
+    ports: [25, 587, 465],
+    domains: [
       {
-        name: 'eng-dashboard',
-        match: { domains: ['eng.example.com'], ports: [443] },
-        action: {
-          type: 'forward',
-          targets: [{ host: '192.168.1.51', port: 8080 }],
-          tls: { mode: 'terminate', certificate: 'auto' },
-        },
-        vpn: { enabled: true, allowedServerDefinedClientTags: ['engineering'] },
-        // → alice + bob can access, carol cannot
+        domain: 'example.com',
+        dnsMode: 'internal-dns',
       },
-      // 🌐 Public: no VPN
+    ],
+    routes: [
       {
-        name: 'public-site',
-        match: { domains: ['example.com'], ports: [443] },
+        name: 'inbound-mail',
+        match: { recipients: '*@example.com' },
         action: {
           type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 80 }],
-          tls: { mode: 'terminate', certificate: 'auto' },
+          forward: { host: 'mail-backend.example.com', port: 25 },
         },
       },
     ],
   },
-});
-```
-
-### Client Tags
-
-SmartVPN distinguishes between two types of client tags:
-
-| Tag Type | Set By | Purpose |
-|----------|--------|---------|
-| `serverDefinedClientTags` | Admin (via config or API) | **Trusted** — used for route access control |
-| `clientDefinedClientTags` | Connecting client | **Informational** — displayed in dashboard, never used for security |
-
-Routes with `allowedServerDefinedClientTags` only permit VPN clients whose admin-assigned tags match. Clients cannot influence their own server-defined tags.
-
-### Client Management via OpsServer
-
-The OpsServer dashboard and API provide full VPN client lifecycle management:
-
-- **Create client** — generates WireGuard keypairs, assigns IP, returns a ready-to-use `.conf` file
-- **QR code** — scan with the WireGuard mobile app (iOS/Android) for instant setup
-- **Enable / Disable** — toggle client access without deleting
-- **Rotate keys** — generate fresh keypairs (invalidates old ones)
-- **Export config** — download in WireGuard (`.conf`), SmartVPN (`.json`), or scan as QR code
-- **Telemetry** — per-client bytes sent/received, keepalives, rate limiting
-- **Delete** — remove a client and revoke access
-
-Standard WireGuard clients on any platform (iOS, Android, macOS, Windows, Linux) can connect using the generated `.conf` file or by scanning the QR code — no custom VPN software needed.
-
-## Certificate Management
-
-DcRouter uses [`@push.rocks/smartacme`](https://code.foss.global/push.rocks/smartacme) v9 for ACME certificate provisioning. smartacme v9 brings significant improvements over previous versions:
-
-### How It Works
-
-When a `dnsChallenge` is configured (e.g. with a Cloudflare API key), DcRouter creates a SmartAcme instance that handles DNS-01 challenges for automatic certificate provisioning. SmartProxy calls the `certProvisionFunction` whenever a route needs a TLS certificate, and SmartAcme takes care of the rest.
-
-```typescript
-const router = new DcRouter({
-  smartProxyConfig: {
-    routes: [
+  dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
+  dnsScopes: ['example.com'],
+  publicIp: '203.0.113.10',
+  vpnConfig: {
+    enabled: true,
+    serverEndpoint: 'vpn.example.com',
+    clients: [
       {
-        name: 'secure-app',
-        match: { domains: ['app.example.com'], ports: [443] },
-        action: {
-          type: 'forward',
-          targets: [{ host: '192.168.1.10', port: 8080 }],
-          tls: { mode: 'terminate', certificate: 'auto' }  // ← triggers ACME provisioning
-        }
-      }
+        clientId: 'ops-laptop',
+        description: 'Operations laptop',
+      },
     ],
-    acme: { email: 'admin@example.com', enabled: true, useProduction: true }
   },
-  tls: { contactEmail: 'admin@example.com' },
-  dnsChallenge: { cloudflareApiKey: process.env.CLOUDFLARE_API_KEY }
+  dbConfig: {
+    enabled: true,
+  },
 });
-```
-
-### smartacme v9 Features
-
-| Feature | Description |
-|---------|-------------|
-| **Per-domain deduplication** | Concurrent requests for the same domain share a single ACME operation |
-| **Global concurrency cap** | Default 5 parallel ACME operations to prevent overload |
-| **Account rate limiting** | Sliding window (250 orders / 3 hours) to stay within ACME provider limits |
-| **Structured errors** | `AcmeError` with `isRetryable`, `isRateLimited`, `retryAfter` fields |
-| **Clean shutdown** | `stop()` properly destroys HTTP agents and DNS clients |
-
-### Per-Domain Backoff
-
-DcRouter's `CertProvisionScheduler` adds **per-domain exponential backoff** on top of smartacme's built-in protections. If a DNS-01 challenge fails for a domain:
-
-1. The failure is recorded (persisted to storage)
-2. The domain enters backoff: `min(failures² × 1 hour, 24 hours)`
-3. Subsequent requests for that domain are rejected until the backoff expires
-4. On success, the backoff is cleared
-
-This prevents hammering ACME servers for domains with persistent issues (e.g. missing DNS delegation).
-
-### Fallback to HTTP-01
-
-If DNS-01 fails, the `certProvisionFunction` returns `'http01'` to tell SmartProxy to fall back to HTTP-01 challenge validation. This provides a safety net for domains where DNS-01 isn't viable.
-
-### Certificate Storage
-
-Certificates are persisted via the `StorageBackedCertManager` which uses DcRouter's `StorageManager`. This means certs survive restarts and don't need to be re-provisioned unless they expire.
-
-### Dashboard
-
-The OpsServer includes a **Certificates** view showing:
-- All domains with their certificate status (valid, expiring, expired, failed)
-- Certificate source (ACME, provision function, static)
-- Expiry dates and issuer information
-- Backoff status for failed domains
-- One-click reprovisioning per domain
-- Certificate import and export
-
-## Storage & Database
-
-DcRouter uses a **unified database** (`DcRouterDb`) powered by [`@push.rocks/smartdata`](https://code.foss.global/push.rocks/smartdata) + [`@push.rocks/smartdb`](https://code.foss.global/push.rocks/smartdb) for all persistence. It supports two modes:
-
-### Embedded LocalSmartDb (Default)
-
-Zero-config, file-based MongoDB-compatible database — no external services needed:
-
-```typescript
-dbConfig: { enabled: true }
-// Data stored at ~/.serve.zone/dcrouter/tsmdb by default
-```
-
-### External MongoDB
-
-Connect to an existing MongoDB instance:
 
-```typescript
-dbConfig: {
-  enabled: true,
-  mongoDbUrl: 'mongodb://localhost:27017',
-  dbName: 'dcrouter',
-}
-```
-
-### Disabling the Database
-
-For static, constructor-only deployments where no runtime management is needed:
-
-```typescript
-dbConfig: { enabled: false }
-// Routes come exclusively from constructor config — no CRUD, no persistence
-// OpsServer still runs but management features are disabled
-```
-
-### What's Stored
-
-DcRouterDb persists all runtime state across 15 document classes:
-
-| Category | Documents | Purpose |
-|----------|-----------|---------|
-| **Routes** | `StoredRouteDoc`, `RouteOverrideDoc` | Programmatic routes and hardcoded route overrides |
-| **Certificates** | `ProxyCertDoc`, `AcmeCertDoc`, `CertBackoffDoc` | TLS certs, ACME state, per-domain backoff |
-| **Auth** | `ApiTokenDoc` | API token storage |
-| **Remote Ingress** | `RemoteIngressEdgeDoc` | Edge node registrations |
-| **VPN** | `VpnServerKeysDoc`, `VpnClientDoc` | Server keys and client registrations |
-| **RADIUS** | `VlanMappingsDoc`, `AccountingSessionDoc` | VLAN mappings and accounting sessions |
-| **References** | `SecurityProfileDoc`, `NetworkTargetDoc` | Reusable security profiles and network targets |
-| **Cache** | `CachedEmailDoc`, `CachedIpReputationDoc` | TTL-based caches with automatic cleanup |
-
-## Security Features
-
-### IP Reputation Checking
-
-Automatic IP reputation checks on inbound connections with configurable caching:
-
-```typescript
-// IP reputation is checked automatically for inbound SMTP connections.
-// Results are cached according to cacheConfig.ttlConfig.ipReputation.
-```
-
-### Rate Limiting
-
-Hierarchical rate limits with three levels of specificity:
-
-```typescript
-// Global defaults (via emailConfig.defaults.rateLimits)
-defaults: {
-  rateLimits: {
-    inbound: { messagesPerMinute: 50, connectionsPerIp: 5, recipientsPerMessage: 50 },
-    outbound: { messagesPerMinute: 100 }
-  }
-}
-
-// Per-domain overrides (in domain config)
-{
-  domain: 'high-volume.com',
-  rateLimits: {
-    outbound: { messagesPerMinute: 500 }  // Override for this domain
-  }
-}
-```
-
-**Precedence**: Domain-specific > Pattern-specific > Global
-
-### Content Scanning
-
-```typescript
-action: {
-  type: 'process',
-  options: {
-    contentScanning: true,
-    scanners: [
-      { type: 'spam', threshold: 5.0, action: 'tag' },
-      { type: 'virus', action: 'reject' },
-      { type: 'attachment', blockedExtensions: ['.exe', '.bat', '.scr'], action: 'reject' }
-    ]
-  }
-}
+await router.start();
 ```
 
-## OpsServer Dashboard
+## Operations API and Dashboard
 
-The OpsServer provides a web-based management interface served on port 3000 by default (configurable via `opsServerPort`). It's built with modern web components using [@design.estate/dees-catalog](https://code.foss.global/design.estate/dees-catalog).
+With the database enabled, dcrouter exposes a management plane for:
 
-### Dashboard Views
+- routes and route toggles
+- API tokens
+- source profiles and network targets
+- DNS providers, domains, and records
+- ACME configuration and certificate lifecycle
+- email domains and email operations
+- VPN clients, remote ingress edges, and RADIUS data
 
-| View | Description |
-|------|-------------|
-| 📊 **Overview** | Real-time server stats, CPU/memory, connection counts, email throughput |
-| 🌐 **Network** | Active connections, top IPs, throughput rates, SmartProxy metrics |
-| 📧 **Email** | Queue monitoring (queued/sent/failed), bounce records, security incidents |
-| 🛣️ **Routes** | Merged route list (hardcoded + programmatic), create/edit/toggle/override routes |
-| 🔑 **API Tokens** | Token management with scopes, create/revoke/roll/toggle |
-| 🔐 **Certificates** | Domain-centric certificate overview, status, backoff info, reprovisioning, import/export |
-| 🌍 **RemoteIngress** | Edge node management, connection status, token generation, enable/disable |
-| 🔐 **VPN** | VPN client management, server status, create/toggle/export/rotate/delete clients |
-| 🛡️ **Security Profiles** | Reusable security configurations (IP allow/block lists, rate limits) |
-| 🎯 **Network Targets** | Reusable host:port destinations for route references |
-| 📡 **RADIUS** | NAS client management, VLAN mappings, session monitoring, accounting |
-| 📜 **Logs** | Real-time log viewer with level filtering and search |
-| ⚙️ **Configuration** | Read-only view of current system configuration |
-| 🛡️ **Security** | IP reputation, rate limit status, blocked connections |
+The browser dashboard is built from the `ts_web` package and is served by OpsServer. The same backend is accessible programmatically via TypedRequest or the dedicated API client package.
 
-### API Endpoints
+## Programmatic API Client
 
-All management is done via TypedRequest over HTTP POST to `/typedrequest`:
-
-```typescript
-// Authentication
-'adminLoginWithUsernameAndPassword'   // Login with credentials → returns JWT identity
-'verifyIdentity'                       // Verify JWT token validity
-'adminLogout'                          // End admin session
-
-// Statistics & Health
-'getServerStatistics'                  // Uptime, CPU, memory, connections
-'getHealthStatus'                      // System health check
-'getCombinedMetrics'                   // All metrics in one call
-
-// Email Operations
-'getAllEmails'                          // List all emails (queued/sent/failed)
-'getEmailDetail'                       // Full detail for a specific email
-'resendEmail'                          // Re-queue a failed email
-
-// Certificates
-'getCertificateOverview'               // Domain-centric certificate status
-'reprovisionCertificate'               // Reprovision by route name (legacy)
-'reprovisionCertificateDomain'         // Reprovision by domain (preferred)
-'importCertificate'                    // Import a certificate
-'exportCertificate'                    // Export a certificate
-'deleteCertificate'                    // Delete a certificate
-
-// Remote Ingress
-'getRemoteIngresses'                   // List all edge registrations
-'createRemoteIngress'                  // Register a new edge
-'updateRemoteIngress'                  // Update edge settings
-'deleteRemoteIngress'                  // Remove an edge
-'regenerateRemoteIngressSecret'        // Issue a new secret
-'getRemoteIngressStatus'               // Runtime status of all edges
-'getRemoteIngressConnectionToken'      // Generate a connection token for an edge
-
-// Route Management (JWT or API token auth)
-'getMergedRoutes'                      // List all routes (hardcoded + programmatic)
-'createRoute'                          // Create a new programmatic route
-'updateRoute'                          // Update a programmatic route
-'deleteRoute'                          // Delete a programmatic route
-'toggleRoute'                          // Enable/disable a programmatic route
-'setRouteOverride'                     // Override a hardcoded route
-'removeRouteOverride'                  // Remove a hardcoded route override
-
-// API Token Management (admin JWT only)
-'createApiToken'                       // Create API token → returns raw value once
-'listApiTokens'                        // List all tokens (without secrets)
-'revokeApiToken'                       // Delete an API token
-'rollApiToken'                         // Regenerate token secret
-'toggleApiToken'                       // Enable/disable a token
-
-// Configuration (read-only)
-'getConfiguration'                     // Current system config
-
-// Logs
-'getRecentLogs'                        // Retrieve system logs with filtering
-'getLogStream'                         // Stream live logs
-
-// VPN
-'getVpnClients'                        // List all registered VPN clients
-'getVpnStatus'                         // VPN server status (running, subnet, port, keys)
-'createVpnClient'                      // Create client → returns WireGuard config (shown once)
-'deleteVpnClient'                      // Remove a VPN client
-'enableVpnClient'                      // Enable a disabled client
-'disableVpnClient'                     // Disable a client
-'rotateVpnClientKey'                   // Generate new keys (invalidates old ones)
-'exportVpnClientConfig'                // Export WireGuard (.conf) or SmartVPN (.json) config
-'getVpnClientTelemetry'                // Per-client bytes sent/received, keepalives
-
-// RADIUS
-'getRadiusSessions'                    // Active RADIUS sessions
-'getRadiusClients'                     // List NAS clients
-'getRadiusStatistics'                  // RADIUS stats
-'setRadiusClient'                      // Add/update NAS client
-'removeRadiusClient'                   // Remove NAS client
-'getVlanMappings'                      // List VLAN mappings
-'setVlanMapping'                       // Add/update VLAN mapping
-'removeVlanMapping'                    // Remove VLAN mapping
-'testVlanAssignment'                   // Test what VLAN a MAC gets
-
-// Security Profiles
-'getSecurityProfiles'                  // List all security profiles
-'getSecurityProfile'                   // Get a single profile by ID
-'createSecurityProfile'                // Create a reusable security profile
-'updateSecurityProfile'                // Update a profile (propagates to referencing routes)
-'deleteSecurityProfile'                // Delete a profile (with optional force)
-'getSecurityProfileUsage'              // Get routes referencing a profile
-
-// Network Targets
-'getNetworkTargets'                    // List all network targets
-'getNetworkTarget'                     // Get a single target by ID
-'createNetworkTarget'                  // Create a reusable host:port target
-'updateNetworkTarget'                  // Update a target (propagates to referencing routes)
-'deleteNetworkTarget'                  // Delete a target (with optional force)
-'getNetworkTargetUsage'                // Get routes referencing a target
-```
-
-## API Client
-
-DcRouter ships with a typed, object-oriented API client for programmatic management of a running instance. Install it separately or import from the main package:
+Use the API client when you want automation or integration code instead of clicking through the dashboard.
 
 ```bash
 pnpm add @serve.zone/dcrouter-apiclient
-# or import from the main package:
-# import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
 ```
 
-### Quick Example
-
 ```typescript
 import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
 
-const client = new DcRouterApiClient({ baseUrl: 'https://dcrouter.example.com' });
+const client = new DcRouterApiClient({
+  baseUrl: 'https://dcrouter.example.com',
+});
+
 await client.login('admin', 'password');
 
-// OO resource instances with methods
 const { routes } = await client.routes.list();
-await routes[0].toggle(false);
+const systemRoutes = routes.filter((route) => route.origin !== 'api');
+
+if (systemRoutes[0]) {
+  await systemRoutes[0].toggle(false);
+}
 
-// Builder pattern for creation
-const newRoute = await client.routes.build()
+await client.routes.build()
   .setName('api-gateway')
   .setMatch({ ports: 443, domains: ['api.example.com'] })
-  .setAction({ type: 'forward', targets: [{ host: 'backend', port: 8080 }] })
-  .setTls({ mode: 'terminate', certificate: 'auto' })
-  .save();
-
-// Manage certificates
-const { certificates, summary } = await client.certificates.list();
-await certificates[0].reprovision();
-
-// Create API tokens with builder
-const token = await client.apiTokens.build()
-  .setName('ci-token')
-  .setScopes(['routes:read', 'routes:write'])
-  .setExpiresInDays(90)
+  .setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8081 }] })
   .save();
-console.log(token.tokenValue); // only available at creation
-
-// Remote ingress edges
-const edge = await client.remoteIngress.build()
-  .setName('edge-nyc-01')
-  .setListenPorts([80, 443])
-  .save();
-const connToken = await edge.getConnectionToken();
-
-// Read-only managers
-const health = await client.stats.getHealth();
-const config = await client.config.get();
-const { logs } = await client.logs.getRecent({ level: 'error', limit: 50 });
-```
-
-### Resource Managers
-
-| Manager | Operations |
-|---------|-----------|
-| `client.routes` | `list()`, `create()`, `build()` → Route: `update()`, `delete()`, `toggle()`, `setOverride()`, `removeOverride()` |
-| `client.certificates` | `list()`, `import()` → Certificate: `reprovision()`, `delete()`, `export()` |
-| `client.apiTokens` | `list()`, `create()`, `build()` → ApiToken: `revoke()`, `roll()`, `toggle()` |
-| `client.remoteIngress` | `list()`, `getStatuses()`, `create()`, `build()` → RemoteIngress: `update()`, `delete()`, `regenerateSecret()`, `getConnectionToken()` |
-| `client.stats` | `getServer()`, `getEmail()`, `getDns()`, `getSecurity()`, `getConnections()`, `getQueues()`, `getHealth()`, `getNetwork()`, `getCombined()` |
-| `client.config` | `get(section?)` |
-| `client.logs` | `getRecent()`, `getStream()` |
-| `client.emails` | `list()` → Email: `getDetail()`, `resend()` |
-| `client.radius` | `.clients`, `.vlans`, `.sessions` sub-managers + `getStatistics()`, `getAccountingSummary()` |
-
-See the [full API client documentation](./ts_apiclient/readme.md) for detailed usage of every manager, builder, and resource class.
-
-## API Reference
-
-### DcRouter Class
-
-```typescript
-import { DcRouter } from '@serve.zone/dcrouter';
-
-const router = new DcRouter(options: IDcRouterOptions);
 ```
 
-#### Methods
-
-| Method | Description |
-|--------|-------------|
-| `start(): Promise<void>` | Start all configured services |
-| `stop(): Promise<void>` | Gracefully stop all services |
-| `updateSmartProxyConfig(config): Promise<void>` | Hot-update SmartProxy routes |
-| `updateEmailConfig(config): Promise<void>` | Hot-update email configuration |
-| `updateEmailRoutes(routes): Promise<void>` | Update email routing rules at runtime |
-| `updateRadiusConfig(config): Promise<void>` | Hot-update RADIUS configuration |
-| `getStats(): any` | Get real-time statistics from all services |
-
-#### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `options` | `IDcRouterOptions` | Current configuration |
-| `smartProxy` | `SmartProxy` | SmartProxy instance |
-| `smartAcme` | `SmartAcme` | SmartAcme v9 certificate manager instance |
-| `emailServer` | `UnifiedEmailServer` | Email server instance (from smartmta) |
-| `dnsServer` | `DnsServer` | DNS server instance |
-| `radiusServer` | `RadiusServer` | RADIUS server instance |
-| `remoteIngressManager` | `RemoteIngressManager` | Edge registration CRUD manager |
-| `tunnelManager` | `TunnelManager` | Tunnel lifecycle and status manager |
-| `vpnManager` | `VpnManager` | VPN server lifecycle and client CRUD manager |
-| `opsServer` | `OpsServer` | OpsServer/dashboard instance |
-| `metricsManager` | `MetricsManager` | Metrics collector |
-| `dcRouterDb` | `DcRouterDb` | Unified database instance (smartdata + smartdb) |
-| `routeConfigManager` | `RouteConfigManager` | Programmatic route CRUD manager |
-| `apiTokenManager` | `ApiTokenManager` | API token management |
-| `referenceResolver` | `ReferenceResolver` | Security profile and network target resolver |
-
-### Re-exported Types
-
-DcRouter re-exports key types for convenience:
+See `./ts_apiclient/readme.md` for the dedicated API-client package docs.
 
-```typescript
-import {
-  DcRouter,
-  IDcRouterOptions,
-  UnifiedEmailServer,
-  type IUnifiedEmailServerOptions,
-  type IEmailRoute,
-  type IEmailDomainConfig,
-  type IHttp3Config,
-} from '@serve.zone/dcrouter';
-```
-
-## Sub-Modules
+## Published Modules
 
-DcRouter is published as a monorepo with separately-installable interface and web packages:
+This repository publishes multiple modules from the same codebase.
 
-| Package | Description | Install |
-|---------|-------------|---------|
-| [`@serve.zone/dcrouter`](https://www.npmjs.com/package/@serve.zone/dcrouter) | Main package — the full router | `pnpm add @serve.zone/dcrouter` |
-| [`@serve.zone/dcrouter-interfaces`](https://www.npmjs.com/package/@serve.zone/dcrouter-interfaces) | TypedRequest interfaces for the OpsServer API | `pnpm add @serve.zone/dcrouter-interfaces` |
-| [`@serve.zone/dcrouter-apiclient`](https://www.npmjs.com/package/@serve.zone/dcrouter-apiclient) | OO API client with builder pattern | `pnpm add @serve.zone/dcrouter-apiclient` |
-| [`@serve.zone/dcrouter-web`](https://www.npmjs.com/package/@serve.zone/dcrouter-web) | Web dashboard components | `pnpm add @serve.zone/dcrouter-web` |
+| Module | Purpose | Docs |
+| --- | --- | --- |
+| `@serve.zone/dcrouter` | Main orchestrator and server package | `./readme.md` |
+| `@serve.zone/dcrouter-interfaces` | Shared TypedRequest request and data interfaces | `./ts_interfaces/readme.md` |
+| `@serve.zone/dcrouter-migrations` | Startup migration runner for dcrouter data | `./ts_migrations/readme.md` |
+| `@serve.zone/dcrouter-web` | Web dashboard entry and UI components | `./ts_web/readme.md` |
+| `@serve.zone/dcrouter-apiclient` | Typed OO API client | `./ts_apiclient/readme.md` |
 
-You can also import directly from the main package:
-
-```typescript
-import { data, requests } from '@serve.zone/dcrouter/interfaces';
-import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
-```
-
-## Testing
-
-DcRouter includes a comprehensive test suite covering all system components:
+## Development and Testing
 
 ```bash
-# Run all tests
+pnpm run build
 pnpm test
-
-# Run a specific test file
-tstest test/test.jwt-auth.ts --verbose
-
-# Run with extended timeout
-tstest test/test.opsserver-api.ts --verbose --timeout 60
 ```
 
-### Test Coverage
-
-| Test File | Area | Tests |
-|-----------|------|-------|
-| `test.apiclient.ts` | API client instantiation, builders, resource hydration, exports | 18 |
-| `test.contentscanner.ts` | Content scanning (spam, phishing, malware, attachments) | 13 |
-| `test.dcrouter.email.ts` | Email config, domain and route setup | 4 |
-| `test.dns-server-config.ts` | DNS record parsing, grouping, extraction | 5 |
-| `test.dns-socket-handler.ts` | DNS socket handler and route generation | 6 |
-| `test.errors.ts` | Error classes, handler, retry utilities | 5 |
-| `test.http3-augmentation.ts` | HTTP/3 route augmentation, qualification, opt-in/out, QUIC settings | 20 |
-| `test.ipreputationchecker.ts` | IP reputation, DNSBL, caching, risk classification | 10 |
-| `test.jwt-auth.ts` | JWT login, verification, logout, invalid credentials | 8 |
-| `test.opsserver-api.ts` | Health, statistics, configuration, log APIs | 8 |
-| `test.protected-endpoint.ts` | Admin auth, identity verification, public endpoints | 8 |
-| `test.reference-resolver.ts` | Security profiles, network targets, route resolution | 20 |
-| `test.security-profiles-api.ts` | Profile/target API endpoints, auth enforcement | 13 |
-
-## Docker / OCI Container Deployment
-
-DcRouter ships with a production-ready `Dockerfile` and supports environment-variable-driven configuration for OCI container deployments. The container image includes tini as PID 1 (via the base image), proper health checks, and configurable resource limits. When `DCROUTER_MODE=OCI_CONTAINER` is set, DcRouter automatically reads configuration from environment variables (and optionally from a JSON config file).
-
-### Running with Docker
+Target a single test file while working on one area:
 
 ```bash
-docker run -d \
-  --ulimit nofile=65536:65536 \
-  -e DCROUTER_TLS_EMAIL=admin@example.com \
-  -e DCROUTER_PUBLIC_IP=203.0.113.1 \
-  -e DCROUTER_DNS_NS_DOMAINS=ns1.example.com,ns2.example.com \
-  -e DCROUTER_DNS_SCOPES=example.com \
-  -p 80:80 -p 443:443 -p 25:25 -p 587:587 -p 465:465 \
-  -p 53:53/udp -p 3000:3000 -p 8443:8443 \
-  code.foss.global/serve.zone/dcrouter:latest
+tstest test/test.dns-runtime-routes.node.ts --verbose
 ```
 
-> ⚡ **Production tip:** Always set `--ulimit nofile=65536:65536` for production deployments. DcRouter will log a warning at startup if the file descriptor limit is below 65536.
-
-### Environment Variables
-
-| Variable | Description | Default | Example |
-|----------|-------------|---------|---------|
-| `DCROUTER_MODE` | Container mode (set automatically in image) | `OCI_CONTAINER` | — |
-| `DCROUTER_CONFIG_PATH` | Path to JSON config file (env vars override) | — | `/config/dcrouter.json` |
-| `DCROUTER_BASE_DIR` | Base data directory | `~/.serve.zone/dcrouter` | `/data/dcrouter` |
-| `DCROUTER_TLS_EMAIL` | ACME contact email | — | `admin@example.com` |
-| `DCROUTER_TLS_DOMAIN` | Primary TLS domain | — | `example.com` |
-| `DCROUTER_PUBLIC_IP` | Public IP for DNS records | — | `203.0.113.1` |
-| `DCROUTER_PROXY_IPS` | Comma-separated ingress proxy IPs | — | `198.51.100.1,198.51.100.2` |
-| `DCROUTER_DNS_NS_DOMAINS` | Comma-separated nameserver domains | — | `ns1.example.com,ns2.example.com` |
-| `DCROUTER_DNS_SCOPES` | Comma-separated authoritative domains | — | `example.com,other.com` |
-| `DCROUTER_EMAIL_HOSTNAME` | SMTP server hostname | — | `mail.example.com` |
-| `DCROUTER_EMAIL_PORTS` | Comma-separated email ports | — | `25,587,465` |
-| `DCROUTER_CACHE_ENABLED` | Enable/disable cache database | `true` | `false` |
-| `DCROUTER_HEAP_SIZE` | Node.js V8 heap size in MB | `512` | `1024` |
-| `DCROUTER_MAX_CONNECTIONS` | Global max concurrent connections | `50000` | `100000` |
-| `DCROUTER_MAX_CONNECTIONS_PER_IP` | Max connections per source IP | `100` | `200` |
-| `DCROUTER_CONNECTION_RATE_LIMIT` | Max new connections/min per IP | `600` | `1200` |
-
-### Exposed Ports
-
-The container exposes all service ports:
-
-| Port(s) | Protocol | Service |
-|---------|----------|---------|
-| 80, 443 | TCP | HTTP/HTTPS (SmartProxy) |
-| 25, 587, 465 | TCP | SMTP, Submission, SMTPS |
-| 53 | TCP/UDP | DNS |
-| 1812, 1813 | UDP | RADIUS auth/acct |
-| 3000 | TCP | OpsServer dashboard |
-| 8443 | TCP | Remote ingress tunnels |
-| 51820 | UDP | WireGuard VPN |
-| 29000–30000 | TCP | Dynamic port range |
-
-### Building the Image
-
-```bash
-pnpm run build:docker    # Build the container image
-pnpm run release:docker  # Push to registry
-```
+## Notes for Operators
 
-The Docker build supports multi-platform (`linux/amd64`, `linux/arm64`) via [tsdocker](https://code.foss.global/git.zone/tsdocker).
+- Database-backed management features depend on `dbConfig.enabled !== false`.
+- If you disable the DB, constructor-configured services still run, but persistent management features are limited.
+- Nameserver domains are still required for DNS bootstrap and DoH route generation.
+- HTTP/3 is enabled by default for qualifying HTTPS routes unless disabled globally or per route.
 
 ## License and Legal Information