Add roadmap and update README

2026-02-27 05:47:38 +00:00 · 2026-02-24 09:32:21 -05:00
parent 85d1083bae
commit 0c6ab72561
2 changed files with 242 additions and 19 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,136 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# VectorDNS
+
+DNS lookup, WHOIS, and domain monitoring tool. Search nameservers, check domain availability, and track DNS record changes over time.
+
+## Features
+
+- **DNS Record Lookup** — Query A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, and SRV records for any domain
+- **WHOIS Lookup** — View registrar, registration/expiration dates, nameservers, and domain status
+- **Domain Availability** — Check if a domain is registered or available via IANA RDAP
+- **Domain Monitoring** — Save domains to a dashboard, track DNS changes over time, get alerts when records change
+- **Change Detection** — Daily automated re-checks with visual diffs showing what changed
+- **Notifications** — In-app notification feed + email alerts via Resend
+- **Dark Mode** — Dark theme by default with light mode toggle
+
+## Tech Stack
+
+- **Framework**: Next.js 16 (App Router) + React 19
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS v4 + shadcn/ui
+- **Auth & Database**: Supabase (auth, Postgres, RLS, realtime)
+- **DNS**: Tangerine (DNS-over-HTTPS via Cloudflare/Google)
+- **WHOIS**: whoiser (RDAP-based, free)
+- **Email**: Resend
+- **Deployment**: Vercel
+- **Package Manager**: Bun

 ## Getting Started

-First, run the development server:
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.3
+- A [Supabase](https://supabase.com) project (free tier works)
+- (Optional) [Resend](https://resend.com) API key for email alerts
+
+### Setup

 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
+# Clone and install
+git clone <repo-url>
+cd vectordns
+bun install
+
+# Configure environment
+cp .env.local.example .env.local
+# Fill in your Supabase URL, anon key, and other values
+
+# Run database migrations
+# (see supabase/migrations/ once they exist)
+
+# Start dev server
 bun dev
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open [http://localhost:3000](http://localhost:3000) to see the app.

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+### Environment Variables

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+| Variable | Required | Description |
+|---|---|---|
+| `NEXT_PUBLIC_SUPABASE_URL` | Yes | Your Supabase project URL |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Yes | Supabase anonymous/public key |
+| `SUPABASE_SERVICE_ROLE_KEY` | Yes | Service role key (for cron jobs) |
+| `CRON_SECRET` | Yes | Secret to authenticate Vercel cron requests |
+| `RESEND_API_KEY` | No | Resend API key for email notifications |

-## Learn More
+## Project Structure

-To learn more about Next.js, take a look at the following resources:
+```
+app/
+  page.tsx                    # Landing page with search
+  layout.tsx                  # Root layout (theme, fonts, metadata)
+  globals.css                 # Tailwind v4 + shadcn/ui CSS vars
+  lookup/[domain]/page.tsx    # DNS results page (public)
+  auth/                       # Login, signup, OAuth callback
+  dashboard/                  # Authenticated domain tracking
+  api/
+    dns/lookup/               # DNS record lookup endpoint
+    whois/lookup/             # WHOIS lookup endpoint
+    availability/check/       # Domain availability endpoint
+    domains/                  # Saved domains CRUD
+    cron/check-domains/       # Daily re-check (Vercel cron)
+    notifications/            # Notification endpoints
+components/
+  ui/                         # shadcn/ui components
+  layout/                     # Header, footer, sidebar
+  lookup/                     # Search form, record displays
+  dashboard/                  # Domain list, detail, diff views
+lib/
+  dns/                        # Tangerine DNS service
+  whois/                      # whoiser WHOIS service
+  availability/               # RDAP availability service
+  monitoring/                 # Change detection + snapshot logic
+  notifications/              # Notification service
+  email/                      # Resend email functions
+  supabase/                   # Server/client/middleware clients
+  auth/                       # Auth server actions
+  types/                      # Shared TypeScript types
+supabase/
+  migrations/                 # SQL schema + RLS policies
+```

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Current Status

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+### Done

-## Deploy on Vercel
+- [x] Project scaffolding (Next.js 16, Tailwind v4, TypeScript)
+- [x] shadcn/ui setup with dark mode (next-themes)
+- [x] Landing page with domain search form

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+### TODO

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+See [ROADMAP.md](./ROADMAP.md) for the full phased build plan. Next up:
+
+- [ ] TypeScript type definitions (`lib/types/`)
+- [ ] Supabase schema + migrations + RLS
+- [ ] DNS / WHOIS / availability service layers
+- [ ] API routes for public lookups
+- [ ] Supabase auth (GitHub, Google, email, magic link)
+- [ ] DNS results page (`/lookup/[domain]`)
+- [ ] Dashboard with domain tracking
+- [ ] Change detection + daily cron
+- [ ] Notifications (in-app + email)
+
+## Scripts
+
+```bash
+bun dev        # Start development server
+bun run build  # Production build
+bun start      # Start production server
+bun lint       # Run ESLint
+bun test       # Run integration tests
+```
+
+## License
+
+GPL-2.0
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -0,0 +1,123 @@
+# 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) |