Document project architecture, setup, usage, and API endpoints

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
2026-08-27 10:47:01 +00:00 · 2025-05-24 02:16:17 +00:00
parent 31f81a754a
commit ae19ec9c3d
6 changed files with 1955 additions and 0 deletions
@@ -0,0 +1,118 @@
+# 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