# VectorDNS Roadmap

## Overview

VectorDNS is a web-based DNS toolkit. Anyone can look up DNS records, WHOIS data, and domain availability without signing in. Authenticated users get a persistent dashboard to save domains, track DNS changes over time, and receive alerts when something changes.

---

## Tech Stack

| Layer | Choice |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript (strict) |
| Styling | Tailwind CSS v4 + shadcn/ui |
| Auth & DB | Supabase (`@supabase/ssr`) |
| DNS Lookups | Tangerine (DNS-over-HTTPS) |
| WHOIS | whoiser (RDAP, free) |
| Availability | IANA RDAP API (free) |
| Email Alerts | Resend |
| Deployment | Vercel |
| Package Manager | Bun |

---

## Phase 1 — Foundation

Everything needed before any features can work.

- [ ] **TypeScript types** — Define shared types for DNS records, WHOIS data, availability results, and database models (`lib/types/`)
- [ ] **Supabase schema** — Create migration files for all tables: `profiles`, `saved_domains`, `dns_history`, `availability_history`, `notifications`. Enable Row Level Security on every table.
- [ ] **Supabase client setup** — Server client, browser client, and middleware for session refresh (`lib/supabase/`). Use `@supabase/ssr` only (auth-helpers is deprecated).
- [ ] **Project config** — `.env.local.example` with all required env vars, `vercel.json` with cron schedule, typed env accessor (`lib/env.ts`)

## Phase 2 — Core Services

The backend logic that powers lookups. No UI yet — just service layers and API routes.

- [ ] **DNS service** — Install `tangerine`. Create `lib/dns/` that queries all 9 record types (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, SRV) via DNS-over-HTTPS. Returns structured results, never throws on missing records.
- [ ] **WHOIS service** — Install `whoiser`. Create `lib/whois/` that extracts registrar, dates, nameservers, status. Graceful error on unsupported TLDs.
- [ ] **Availability service** — Fetch `https://rdap.org/domain/{domain}`. 404 = available, 200 = registered. No API key needed. Create `lib/availability/`.
- [ ] **DNS lookup API** — `POST /api/dns/lookup` — public, rate-limited (30 req/min per IP)
- [ ] **WHOIS lookup API** — `POST /api/whois/lookup` — public, rate-limited (20 req/min per IP)
- [ ] **Availability check API** — `POST /api/availability/check` — public
- [ ] **Integration tests** for each API route (use `bun test`)

## Phase 3 — Authentication

- [ ] **Auth system** — Configure Supabase Auth with all 4 providers: GitHub OAuth, Google OAuth, email+password, magic link
- [ ] **Auth actions** — Server actions for sign in/out across all providers (`lib/auth/actions.ts`)
- [ ] **OAuth callback** — `app/auth/callback/route.ts` handles code exchange
- [ ] **Middleware** — Protect `/dashboard/*` routes, redirect unauthenticated users to login
- [ ] **Login/signup pages** — OAuth buttons, email form, magic link option

## Phase 4 — Public UI

Pages that work without an account.

- [ ] **App shell** — Root layout with header (logo, nav, theme toggle, auth button), footer
- [ ] **Homepage** — *(done)* Hero, search form, feature cards
- [ ] **DNS results page** — `app/lookup/[domain]/page.tsx` — tabbed DNS records, WHOIS card, availability badge. Shareable URL.
- [ ] **Save to Dashboard button** — Shown to logged-in users on the results page

## Phase 5 — Dashboard

Authenticated features behind `/dashboard`.

- [ ] **Dashboard layout** — Sidebar navigation, overview stats (saved count, recent changes, unread notifications)
- [ ] **Saved domains CRUD** — `GET/POST /api/domains`, `GET/PUT/DELETE /api/domains/[id]`
- [ ] **Domains list page** — Table/card grid of saved domains with add/delete/re-check actions
- [ ] **Domain detail page** — Tabbed view: current DNS records, DNS history timeline, change diff (old vs new), availability history, WHOIS data
- [ ] **Notes & tags** — Inline-editable notes (plain text) and tags (chip input) per domain, auto-saves on blur
- [ ] **Manual re-check** — `POST /api/domains/[id]/check` triggers fresh DNS/WHOIS/availability lookups and stores snapshots

## Phase 6 — Monitoring & Alerts

Automated change detection and notifications.

- [ ] **Change detection service** — `lib/monitoring/` — compares DNS snapshots, detects added/removed records, availability flips, expiry changes
- [ ] **Daily cron job** — `GET /api/cron/check-domains` (secured with `CRON_SECRET`) — re-checks up to 50 domains per run, stores new snapshots, creates notifications on change
- [ ] **In-app notifications** — `notifications` table + API routes + bell icon with unread count in header + notification center page
- [ ] **Email alerts** — Install `resend`. Send emails on DNS changes, availability changes, expiry warnings. Respects user preference (`notification_email` toggle in profile).

## Phase 7 — Settings & Polish

- [ ] **User settings page** — Profile info, notification email toggle, sign out, delete account
- [ ] **Error handling** — Root error boundary (`app/error.tsx`), 404 page, loading skeletons for lookup and dashboard pages
- [ ] **Toasts** — Wire up `sonner` globally for success/error feedback
- [ ] **SEO** — Page-specific metadata, OG image, `robots.ts` (disallow dashboard/api), `sitemap.ts`

## Phase 8 — Testing & QA

- [ ] **Consolidate integration tests** — All API routes, change detection logic, auth flows
- [ ] **Build verification** — `bun run build` passes, zero TS errors, zero lint issues
- [ ] **Manual QA pass** — Walk through every page, both light and dark mode

---

## Out of Scope (Future)

These are explicitly not part of the current build:

- Registrar API integration / domain purchasing
- Paid DNS API providers (architecture supports swapping, but free-only for now)
- Bulk domain scanning
- Billing / subscriptions
- Browser push notifications
- Rich text notes
- Domain sharing between users

---

## Key Architecture Decisions

| Decision | Rationale |
|---|---|
| `@supabase/ssr` not `auth-helpers` | auth-helpers is deprecated as of late 2025 |
| Tangerine (DoH) not Node `dns` | Works in serverless (Vercel), no system resolver dependency |
| IANA RDAP for availability | Free, no API key, standard protocol. Provider interface allows swapping to paid APIs later. |
| Resend not Supabase SMTP | Supabase built-in SMTP has a 3 emails/hour limit |
| In-memory rate limiting | Simple Map-based per-IP. No Redis dependency for MVP. |
| `TEXT[]` for tags | Postgres array, no separate tags table. Good enough for MVP. |
| Daily cron, 50 domains/run | Fits Vercel hobby tier (10s function timeout, 1 cron/day) |