DNS Management System Design Document

Overview

The DNS Management System provides a unified interface for managing DNS zones and records through bidirectional synchronization with a Technitium DNS Server. The system is integrated into the Local dashboard section and allows users to manage their DNS infrastructure through a single interface while maintaining consistency between the local database and the DNS server.

Architecture

System Components

Frontend Interface
- Location: /apps/webs/dodev/app/dashboard/local/zones/page.tsx
- Purpose: Primary UI for DNS zone and record management
- Features:
  - Location-based zone organization
  - Real-time DNS zone import from Technitium server
  - CRUD operations for domains and DNS records
  - Enable/disable status management
  - Visual status indicators (green/orange badges)
API Layer
- Base path: /apps/webs/dodev/app/api/dns/
- Routes:
  - domains/ - Domain CRUD operations
  - records/ - DNS record management
  - zones/import/ - Import zones from Technitium
  - zones/sync/ - Sync operations
  - zones/toggle/ - Enable/disable zones
DNS Client Library
- Location: /apps/webs/dodev/lib/dns-client.ts
- Purpose: TypeScript client for Technitium DNS Server API
- Features:
  - Authentication management
  - Zone and record operations
  - Error handling with custom TechnitiumAPIError class
Database Layer
- Platform: Convex
- Tables:
  - loc_locations - Physical/logical locations
  - loc_domains - DNS domains/zones
  - loc_zones - DNS A records

Key Features

1. Bidirectional Synchronization

All CRUD operations update both the local Convex database and the Technitium DNS server simultaneously, ensuring data consistency across systems.

2. Location-Based Organization

DNS zones are organized by location (e.g., home, office, cloud), allowing for logical grouping of infrastructure.

3. Primary Zone Import

The system imports all "Primary" type zones from the Technitium server, not limited to specific TLDs.

4. A Record Focus

Currently focuses on A record management, with support for:

Subdomain records
Root domain records (@)
IP address mapping
TTL configuration

5. Status Management

Enable/disable functionality for zones with visual indicators:

Green badge: Enabled
Orange badge: Disabled

API Endpoints

Domain Management (`/api/dns/domains/`)

POST: Create new zone in Technitium and Convex
DELETE: Remove zone from both systems

Record Management (`/api/dns/records/`)

GET: Fetch A records for a specific zone
POST: Add new A record
DELETE: Remove A record

Zone Operations (`/api/dns/zones/`)

import/POST: Import Primary zones from Technitium
toggle/POST: Enable/disable zone in Technitium
sync/POST: Full synchronization operation

Configuration

Environment Variables

TECHNITIUM_DNS_URL=http://10.3.3.3:5380  # Technitium server URL
TECHNITIUM_USERNAME=admin                 # Admin username
TECHNITIUM_PASSWORD=your_password         # Admin password

Default Settings

DNS Server: 10.3.3.3
Port: 5380 (Technitium default)
Timeout: 30 seconds
Default TTL: 300 seconds

Data Flow

Import Process

User clicks "Import DNS" button
System authenticates with Technitium server
Fetches all zones and filters for Primary type
For each zone:
- Fetches all records
- Filters for A records
- Creates/updates domain in Convex
- Creates/updates records in Convex
- Syncs enable/disable status

CRUD Operations

User performs action in UI
Frontend calls appropriate API endpoint
API authenticates with Technitium
Performs operation on Technitium first
If successful, updates Convex database
Returns success/error to frontend

Status Toggle

User clicks enable/disable button
API calls Technitium enable/disable endpoint
Updates local database status
UI reflects new status immediately

Security Considerations

Authentication: Uses environment variables for Technitium credentials
API Access: All DNS operations require authenticated sessions
Network: Communication with Technitium server over HTTP (consider HTTPS in production)
Validation: Input validation on both frontend and API layers

UI/UX Design

Zone Cards

Minimal design with zone name and description
Status badge in bottom-right corner
Hover effects for interactivity
Click to select and view records
Edit/Delete actions via icon buttons

Records Table

Clean table layout with A record details
Name, Type, IP Address, TTL, Status columns
Inline enable/disable badges
Row hover effects
Click to edit functionality

Import Feedback

Real-time progress during import
Success/error summary card
Details on zones found and records imported
Persistent until manually dismissed

Future Enhancements

Additional Record Types: Support for CNAME, MX, TXT, etc.
Bulk Operations: Select multiple records for bulk updates
Zone Templates: Pre-configured zone templates
DNSSEC Support: Enable DNSSEC management
Audit Logging: Track all DNS changes
Backup/Restore: Zone backup and restoration
API Rate Limiting: Implement rate limiting for API calls
Webhook Integration: Notify external systems of DNS changes

Error Handling

API Errors

Network timeouts (30s default)
Authentication failures
Invalid zone/record data
Duplicate zone handling during import

UI Error States

Loading spinners during operations
Error alerts with descriptive messages
Graceful degradation on connection failure
Retry mechanisms for failed operations

Performance Considerations

Pagination: Currently loads all zones/records (consider pagination for large datasets)
Caching: No caching implemented (consider for read operations)
Batch Operations: Import processes zones sequentially (consider parallel processing)
Real-time Updates: Uses Convex real-time subscriptions for instant UI updates

Maintenance

Adding New Record Types

Update DNSRecordType in dns-client.ts
Modify record filtering in API routes
Update UI components to handle new types
Add appropriate form fields for record-specific data

Updating Technitium API

Modify TechnitiumDNSClient methods
Update error handling for new error types
Adjust API response parsing if needed
Test all CRUD operations

Testing Recommendations

Unit Tests: DNS client library methods
Integration Tests: API endpoints with mock Technitium
E2E Tests: Full user workflows
Load Tests: Import performance with many zones
Error Scenarios: Network failures, auth errors, invalid data

Deployment Notes

Ensure environment variables are set in production
Verify network connectivity to Technitium server
Configure firewall rules for DNS server access
Monitor API response times
Set up error logging and alerting