Meal/VectorDNS
1
0
Fork 0
mirror of https://github.com/DevVoxel/VectorDNS.git synced 2026-02-27 05:47:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove old docs dir

Browse Source
This commit is contained in:
Aiden Smith
2026-02-24 19:11:50 -05:00
parent 301402e2b1
commit 466fdd6ef8
3 changed files with 0 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/api-spec.md
View File

@@ -1,135 +0,0 @@
# Go DNS API Specification
Base URL: `https://<vps-host>/api/v1`
All requests require the header `X-API-Key: <shared-secret>`.
---
## Endpoints
### `POST /dns/lookup`
Resolve DNS records for a domain.
**Request:**
```json
{
"domain": "example.com",
"types": ["A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "CAA", "SRV"],
"nameserver": "8.8.8.8"
}
```
- `domain` (required): The domain to query.
- `types` (optional): Record types to query. Defaults to all supported types.
- `nameserver` (optional): Specific nameserver to query. Defaults to system resolver.
**Response (200):**
```json
{
"domain": "example.com",
"nameserver": "8.8.8.8",
"records": {
"A": [{ "value": "93.184.216.34", "ttl": 300 }],
"MX": [{ "value": "mail.example.com", "priority": 10, "ttl": 3600 }]
},
"query_time_ms": 12
}
```
---
### `POST /dns/propagation`
Check DNS propagation across multiple resolvers.
**Request:**
```json
{
"domain": "example.com",
"type": "A",
"resolvers": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
}
```
- `resolvers` (optional): Defaults to a built-in list of public resolvers.
**Response (200):**
```json
{
"domain": "example.com",
"type": "A",
"results": [
{ "resolver": "8.8.8.8", "values": ["93.184.216.34"], "ttl": 300 },
{ "resolver": "1.1.1.1", "values": ["93.184.216.34"], "ttl": 280 },
{ "resolver": "9.9.9.9", "values": ["93.184.216.34"], "ttl": 295 }
],
"consistent": true
}
```
---
### `POST /dns/validate`
DNSSEC validation for a domain.
**Request:**
```json
{
"domain": "example.com"
}
```
**Response (200):**
```json
{
"domain": "example.com",
"dnssec": true,
"chain_valid": true,
"details": "RRSIG verified for A record"
}
```
---
### `GET /health`
Health check. No authentication required.
**Response (200):**
```json
{
"status": "ok",
"version": "0.1.0"
}
```
---
## Error Responses
All errors follow this format:
```json
{
"error": "invalid domain",
"code": "INVALID_DOMAIN"
}
```
| HTTP Status | Code | Description |
|---|---|---|
| 400 | `INVALID_DOMAIN` | Malformed or missing domain |
| 400 | `INVALID_TYPE` | Unsupported record type |
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
| 500 | `DNS_ERROR` | Upstream DNS query failed |
| 500 | `INTERNAL` | Unexpected server error |

78
docs/architecture.md
View File

@@ -1,78 +0,0 @@
# 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

111
docs/feature-plan.md
View File

@@ -1,111 +0,0 @@
# VectorDNS Feature Plan
Decisions captured for current and future development.
---
## Auth & User System
| Feature | Decision | Priority |
|---|---|---|
| OAuth providers | GitHub + Google | MVP |
| Email/password + magic link | Yes | MVP |
| Team/org accounts | Yes, eventually — shared watchlists, role-based access (admin/viewer) | Future |
| User API keys | No — Go server is internal, called only by the Next.js backend | N/A |
### Schema implications (teams)
- Future `teams` table with membership + roles
- `saved_domains` will need an optional `team_id` foreign key
- RLS policies will need team-aware variants
---
## DNS & Monitoring
| Feature | Decision | Priority |
|---|---|---|
| Check intervals | Daily (MVP), then hourly/daily/weekly selectable | MVP → Near-term |
| Realtime monitoring | Not now — possible distant future | Deferred |
| Custom resolvers | Fixed resolvers (Google 8.8.8.8, Cloudflare 1.1.1.1) by default; user-specified resolvers as future feature | MVP → Future |
| Propagation checks | Query multiple resolvers and compare results | Near-term |
| DNSSEC validation | Basic AD flag check (current), deep chain validation later | MVP → Future |
### Go server implications
- Scheduler needed for flexible intervals (hourly/daily/weekly per domain)
- Resolver list should be configurable, not hardcoded (prep for custom resolvers)
- Propagation endpoint: query N resolvers in parallel, return per-resolver results
---
## Alert Channels
| Channel | Priority |
|---|---|
| In-app notification feed | MVP |
| Email (Resend) | MVP |
| Webhooks (user-configured URL) | Near-term |
| Slack integration | Future |
| Discord integration | Future |
### Schema implications
- `notification_channels` table: user_id, type (email/webhook/slack/discord), config (jsonb), enabled
- Webhook: store URL + optional secret for HMAC signing
- Slack/Discord: store webhook URL or OAuth token
---
## Dashboard & UX
| Feature | Decision | Priority |
|---|---|---|
| Domain organization | Tags (current) + folders/groups | Near-term |
| Public sharing | Shareable links for domain DNS snapshots | Near-term |
| Data export | CSV + JSON for DNS history, saved domains, notifications | Near-term |
| Bulk operations | Add/remove/re-check multiple domains at once | Future |
| Search & filter | Filter by tag, folder, record type, change status | Near-term |
### Schema implications (folders)
- `domain_folders` table: id, user_id, name, created_at
- `saved_domains` gets an optional `folder_id` foreign key
- RLS policies for folder ownership
### Schema implications (public sharing)
- `shared_snapshots` table: id, saved_domain_id, share_token (unique), dns_snapshot (jsonb), expires_at, created_at
- Public access via token — no auth required to view
---
## Infrastructure
| Feature | Decision | Priority |
|---|---|---|
| Billing/paid tiers | Freemium — free tier with limits, paid for more domains/features/intervals | Future |
| DNS caching | Redis — external cache for TTL-based DNS result caching | Near-term |
| Self-hosting | Go server only — provide Dockerfile + docker-compose for the DNS API | Near-term |
| Next.js hosting | Vercel only, not self-hostable | — |
### Freemium tier structure (draft)
- **Free**: 5 monitored domains, daily checks, in-app + email alerts
- **Pro**: 50 domains, hourly checks, webhooks, folders, export
- **Team**: everything in Pro + team accounts, shared watchlists
### Go server additions needed
- Redis client (go-redis) for caching layer
- Cache middleware: check Redis before querying DNS, store with TTL
- docker-compose.yml with Go server + Redis for self-hosting
- Rate limiting per API key / tier (when billing is added)
---
## Summary of future schema additions
These tables will be needed as features are built:
| Table | For |
|---|---|
| `teams` | Team/org accounts |
| `team_members` | Membership + roles |
| `domain_folders` | Folder organization |
| `shared_snapshots` | Public shareable links |
| `notification_channels` | Webhook/Slack/Discord config |
| `subscriptions` | Billing tier tracking |