mirror of
https://github.com/freedbygrace/DynamoDNS.git
synced 2026-07-26 11:38:13 +00:00
alphaeusmote
ae19ec9c3d
Adds comprehensive documentation including architecture, API reference, deployment, development, and user guides with README.md. Replit-Commit-Author: Agent Replit-Commit-Session-Id: 9111ef36-26c8-4085-84ca-a35dc1fec1b5 Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/7083d608-d6d3-4a6a-9a27-6286c5109627/910f6160-6716-488e-83e6-61256595c269.jpg
118 lines
6.3 KiB
Markdown
118 lines
6.3 KiB
Markdown
# DynamoDNS Architecture
|
|
|
|
## Overview
|
|
|
|
DynamoDNS is a comprehensive web-based dynamic DNS management platform that offers advanced infrastructure control, monitoring, and multi-provider integration. The application focuses on user experience and security while providing a robust solution for maintaining DNS records across multiple providers.
|
|
|
|
## System Architecture
|
|
|
|
The system is built on a modern web stack with the following components:
|
|
|
|
### Backend
|
|
- **Express.js Server**: Handles API requests, authentication, and business logic
|
|
- **PostgreSQL Database**: Provides robust data storage using the Neon serverless Postgres service
|
|
- **Drizzle ORM**: Manages database interactions and schema definition
|
|
- **Authentication System**: Supports multiple authentication methods (local, LDAP, OIDC)
|
|
- **DNS Provider Modules**: Integrates with various DNS providers (Cloudflare, AWS Route53, GoDaddy, etc.)
|
|
|
|
### Frontend
|
|
- **React**: Powers the user interface
|
|
- **TanStack Query**: Manages data fetching and caching
|
|
- **Shadcn UI**: Provides consistent, accessible UI components
|
|
- **Tailwind CSS**: Handles styling with utility-first approach
|
|
- **Wouter**: Manages client-side routing
|
|
|
|
## Component Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Client Browser │
|
|
└───────────────────────────┬─────────────────────────────────┘
|
|
│
|
|
┌───────────────────────────▼─────────────────────────────────┐
|
|
│ Express Server │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌──────────────┐ ┌────────────┐ │
|
|
│ │ Authentication │ │ API Routes │ │ WebSockets │ │
|
|
│ └─────────────────┘ └──────────────┘ └────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌──────────────┐ ┌────────────┐ │
|
|
│ │ Storage Layer │ │ DNS Provider │ │ Metrics │ │
|
|
│ └────────┬────────┘ │ Modules │ │ Collection │ │
|
|
│ │ └──────┬───────┘ └────────────┘ │
|
|
└───────────┼──────────────────────────────────────────────────┘
|
|
│ │
|
|
┌───────────▼────────┐ ┌────────▼───────────────────────────┐
|
|
│ PostgreSQL DB │ │ External DNS APIs │
|
|
│ (via Drizzle ORM) │ │ (Cloudflare, Route53, GoDaddy) │
|
|
└────────────────────┘ └────────────────────────────────────┘
|
|
```
|
|
|
|
## Database Schema
|
|
|
|
The database schema is defined using Drizzle ORM and includes the following main entities:
|
|
|
|
- **Users**: Application users with authentication details
|
|
- **Customers**: Organizations/accounts using the system
|
|
- **Customer User Assignments**: Many-to-many relationship connecting users to customers
|
|
- **Providers**: DNS service providers integrated with the system
|
|
- **Domains**: DNS domains managed by the system
|
|
- **DNS Records**: Individual DNS records within domains
|
|
- **DNS History**: Historical record of DNS changes
|
|
- **Metrics**: Performance and usage metrics
|
|
- **API Tokens**: Tokens for API authentication
|
|
- **Webhooks**: Notification integration points
|
|
|
|
## Authentication Flow
|
|
|
|
The application supports multiple authentication methods:
|
|
|
|
1. **Local Authentication**: Username/password stored in the database
|
|
2. **LDAP**: Integration with corporate directories
|
|
3. **OpenID Connect**: Single sign-on with identity providers
|
|
|
|
Authentication is managed via Passport.js with session-based authentication for the web interface and token-based authentication for API access.
|
|
|
|
## Authorization Model
|
|
|
|
The system implements a role-based access control (RBAC) model with the following roles:
|
|
|
|
- **Admin**: Full system access
|
|
- **Manager**: Can manage customers, domains, and DNS records
|
|
- **User**: Can manage assigned domains and DNS records
|
|
- **ReadOnly**: View-only access to assigned resources
|
|
- **Custom Roles**: User-defined roles with specific permissions
|
|
|
|
## Data Flow
|
|
|
|
### DNS Record Updates
|
|
|
|
1. User initiates a DNS record update through the UI
|
|
2. Server validates the request and user permissions
|
|
3. Server dispatches the update to the appropriate DNS provider module
|
|
4. Provider module makes API calls to the external DNS service
|
|
5. Results are recorded in the database (success or failure)
|
|
6. Historical entry is created
|
|
7. Metrics are updated
|
|
8. Webhooks are triggered (if configured)
|
|
9. Client is notified of the outcome
|
|
|
|
### Automatic IP Updates
|
|
|
|
For dynamic DNS functionality:
|
|
|
|
1. Client periodically checks for IP changes
|
|
2. When a change is detected, updates are sent to the server
|
|
3. Server processes updates for all DNS records configured for automatic IP updates
|
|
4. External DNS providers are updated
|
|
5. History and metrics are recorded
|
|
|
|
## Security Considerations
|
|
|
|
- **Authentication**: Multiple secure authentication methods
|
|
- **Authorization**: Granular role-based access control
|
|
- **API Tokens**: Scoped access with expiration
|
|
- **Audit Trail**: Comprehensive history logging
|
|
- **Credential Storage**: Secure storage of provider credentials
|
|
- **Input Validation**: Strict validation of all inputs
|
|
- **Rate Limiting**: Protection against abuse |