Add architecture docs and Go microservice to tech stack

2026-02-27 09:57:39 +00:00 · 2026-02-24 13:47:17 -05:00
parent 9a80accaf9
commit f49bdb7099
3 changed files with 219 additions and 1 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,78 @@
+# VectorDNS Architecture
+
+## Overview
+
+VectorDNS uses a hybrid architecture: a Next.js frontend on Vercel and a Go DNS microservice on a VPS.
+
+```
+┌──────────────────────┐        ┌──────────────────────┐
+│   Vercel (Frontend)  │        │    VPS (DNS API)      │
+│                      │        │                       │
+│  Next.js 16          │  HTTP  │  Go microservice      │
+│  React 19            │◄──────►│  miekg/dns            │
+│  Supabase SDK        │        │                       │
+│  Tailwind + shadcn   │        │  - DNS resolution     │
+│                      │        │  - DNSSEC validation   │
+│  Handles:            │        │  - Propagation checks  │
+│  - UI/SSR            │        │  - Monitoring cron     │
+│  - Auth (Supabase)   │        │  - Change detection    │
+│  - WHOIS lookups     │        │                       │
+│  - Static pages      │        └───────────┬───────────┘
+│                      │                    │
+└──────────┬───────────┘                    │ UDP/TCP
+           │                                ▼
+           │                    ┌───────────────────────┐
+           │                    │   DNS Resolvers /      │
+           ▼                    │   Authoritative NS     │
+┌──────────────────────┐        └───────────────────────┘
+│   Supabase           │
+│                      │
+│  - Postgres DB       │
+│  - Auth              │
+│  - Row Level Security│
+└──────────────────────┘
+```
+
+## Why Hybrid
+
+| Concern | Solution |
+|---|---|
+| Frontend hosting, SSR, auth | Vercel (serverless, zero-ops) |
+| DNS resolution, monitoring | Go on VPS (persistent process, no cold starts) |
+| Database, auth state | Supabase (managed Postgres) |
+
+## What Each Service Handles
+
+### Next.js (Vercel)
+
+- All UI rendering (SSR + client)
+- Authentication via Supabase
+- WHOIS lookups (whoiser library)
+- Domain availability checks (IANA RDAP)
+- Dashboard, notifications, settings pages
+- Proxies DNS queries to the Go service
+
+### Go Microservice (VPS)
+
+- DNS record lookups via `miekg/dns` (UDP/TCP, not DoH)
+- Query specific or authoritative nameservers directly
+- DNSSEC validation
+- DNS propagation checking across multiple resolvers
+- Scheduled monitoring (native cron, no serverless time limits)
+- Change detection (diff DNS snapshots, notify on changes)
+
+## Communication
+
+The Next.js API routes call the Go service over HTTPS. The Go service URL is configured via environment variable (`GO_DNS_API_URL`). Requests are authenticated with a shared API key (`GO_DNS_API_KEY`).
+
+```
+Next.js API route → HTTPS → Go DNS API → UDP/TCP → DNS resolvers
+```
+
+## Why Go Over DoH (Tangerine)
+
+- Direct UDP/TCP DNS queries — faster, no middleman
+- Can query authoritative nameservers directly
+- Supports DNSSEC validation, AXFR, propagation checks
+- No cold starts, consistent latency
+- No Vercel function timeout limits for monitoring jobs