System Architecture

Deep dive into NexoralDNS architecture, design patterns, and performance optimization strategies.

System Overview

NexoralDNS is a high-performance DNS server built with advanced features:

Sub-5ms query response times with Redis caching
Domain rerouting (e.g., google.com → ankan.site)
Domain blocking (ads, malware, custom blocks)
User plan management with feature limits
Analytics & logging for query monitoring
Multi-client support with client-specific rules

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT DNS QUERY                             │
│                     (e.g., google.com A record)                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      UDP DNS Server (Port 53)                        │
│                        DNS.Service.ts                                │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     Rules.service.ts (Main Logic)                    │
│                    ┌──────────────────────────┐                      │
│                    │   7-Layer Check System   │                      │
│                    └──────────────────────────┘                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
        ▼                      ▼                      ▼
   [CACHE HIT]           [DB LOOKUP]           [UPSTREAM DNS]
   Return <2ms           Return <5ms           Return <50ms

7-Layer Query Processing

Every DNS query passes through 7 optimization layers for maximum performance and functionality:

Layer 1: Redis Cache (0.5-1ms)

First check the Redis cache for previously resolved queries. This provides sub-millisecond responses for 80%+ of queries.

Layer 2: Service Status (0.5ms)

Verify the DNS service is active. If disabled, return NXDOMAIN immediately.

Layer 3: Block List (0.5ms)

Check if the domain is blocked (globally or for specific clients). Blocked domains return NXDOMAIN and are logged for analytics.

Layer 4: Rewrite Rules (1ms)

Check for domain rerouting rules. If a rewrite exists (e.g., google.com → ankan.site), resolve the target domain and return its IP.

Layer 5: DNS Record Lookup (2ms)

Query MongoDB for custom DNS records. This layer handles user-created domains like "myapp.local".

Layer 6: User Plan Validation (0.5ms)

For custom domains, verify the user's subscription plan is active. Expired plans result in NXDOMAIN.

Layer 7: Upstream DNS (10-50ms)

If no match is found in previous layers, forward to upstream DNS servers (8.8.8.8, 1.1.1.1) and cache the response.

Component Breakdown

1. Client Layer

Web UI (Next.js): User dashboard for managing DNS records
Mobile App: Mobile client for DNS management
CLI Client: Command-line interface
DNS Clients: Any device using the DNS server

2. API Server Layer (Port 4000 - Fastify)

REST API: HTTP endpoints for CRUD operations
Controllers: Request validation and routing
Services: Business logic and database operations
Authentication: JWT-based user authentication

3. DNS Server Layer (Port 53 - UDP)

DNS.Service.ts: Main UDP server on port 53
Rules.service.ts: Core query processing with 7-layer checks
Supporting Services: Database lookups, caching, logging
Global DNS Forwarder: Upstream DNS resolution

4. Caching Layer (Redis)

Redis provides sub-millisecond query responses with the following cache types:

Full DNS responses (binary packets)
DNS records (JSON)
Service status
Rewrite rules
Block lists
User plans

5. Database Layer (MongoDB)

Collections:

dns_records - A, AAAA, CNAME records
dns_rewrites - Domain rerouting rules
dns_blocks - Blocked domains
user_plans - Subscription management
dns_query_logs - Analytics data (30-day TTL)
domains - User-owned domains
service - Service configuration

Database Schema

DNS Rewrites (Domain Rerouting)

{
  _id: ObjectId,
  userId: ObjectId | null,           // null = global rule
  sourceDomain: "google.com",
  targetDomain: "ankan.site",
  targetIP: "1.2.3.4",               // Optional direct IP
  applyToClients: ["192.168.1.5"],   // [] = all clients
  enabled: true,
  ttl: 300,
  priority: 10,                      // Lower = higher priority
  createdAt: Date,
  updatedAt: Date
}

DNS Blocks

{
  _id: ObjectId,
  userId: ObjectId | null,           // null = global block
  domain: "ads.google.com",
  blockType: "exact" | "wildcard",   // exact or *.domain.com
  applyToClients: ["192.168.1.10"],  // [] = all clients
  enabled: true,
  reason: "Malware" | "Ads" | "Custom",
  createdAt: Date
}

User Plans

{
  _id: ObjectId,
  userId: ObjectId,
  planType: "free" | "pro" | "enterprise",
  features: {
    maxRewrites: 10,
    maxBlocks: 100,
    customDNS: true,
    analyticsEnabled: true
  },
  expiresAt: Date,
  status: "active" | "expired" | "suspended",
  createdAt: Date
}

Performance Targets

Check	Target Latency	Notes
Redis Cache Hit	0.5-1ms	80%+ hit rate expected
Service Status	0.5ms	Cached in Redis
Block Check	0.5ms	Redis SET lookup
Rewrite Check	1ms	Redis + fallback DB
DNS Record DB	2-3ms	Redis + MongoDB
User Plan Check	0.5ms	Cached in Redis
Upstream DNS	10-50ms	Only for uncached
Total (Cached)	<2ms	🎯 Target
Total (Uncached DB)	<5ms	🎯 Target
Total (Upstream)	<50ms	Acceptable

Redis Caching Strategy

Cache Key Structure

// Service Status (TTL: 60s)
redis.set('service:status', 'active', 'EX', 60)

// DNS Records (TTL: 300s or record TTL)
redis.set('dns:google.com', '{"value":"1.2.3.4","ttl":300}', 'EX', 300)

// Rewrites (TTL: 300s)
redis.set('rewrite:google.com:192.168.1.5', '{"target":"ankan.site"}', 'EX', 300)

// Blocks (TTL: 600s)
redis.sadd('block:global', 'ads.google.com')

// User Plans (TTL: 300s)
redis.set('plan:userId:507f1f77bcf86cd799439011', '{"status":"active"}', 'EX', 300)

Technology Stack

Runtime: Node.js (TypeScript)
DNS Server: Native UDP server (dgram)
API Server: Fastify
Database: MongoDB
Cache: Redis
Web UI: Next.js + React
Deployment: Docker + Docker Compose

Scalability & High Availability

Redis Cluster

Master-Replica setup for failover protection and high availability.

MongoDB Replica Set

3-node replica set for data redundancy and automatic failover.

DNS Service Clustering

Use PM2 cluster mode to run multiple DNS server instances sharing the same Redis cache.

Security Considerations

Redis Security: Password authentication, localhost binding, TLS for remote
Rate Limiting: Per-IP query limits, DDoS protection
Input Validation: Sanitized domain names, prevent DNS amplification
Access Control: JWT authentication, role-based access

Monitoring & Metrics

Key metrics to track:

Cache hit rate (target: >80%)
P50, P95, P99 latency
Queries per second
Error rate
Database query time
Redis memory usage

Learn More

API Reference - REST API endpoints
Features - Detailed feature documentation
Security - Security best practices