# 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