VectorDNS/README.md

# 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
- **DNS API**: Go microservice on VPS ([`miekg/dns`](https://github.com/miekg/dns) — direct UDP/TCP resolution, DNSSEC, propagation checks)
- **Deployment**: Vercel (frontend) + VPS (Go DNS API)
- **Package Manager**: Bun

## Getting Started

### 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
# Clone and install (GitHub)
git clone https://github.com/DevVoxel/VectorDNS.git
# Or from Gitea mirror
git clone https://git.pawtime.chat/Meal/VectorDNS.git

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) to see the app.

### Environment Variables

| 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 |

## Architecture

VectorDNS uses a hybrid architecture: Next.js on Vercel for the frontend, and a Go microservice on a VPS for DNS resolution and monitoring. See [docs/architecture.md](./docs/architecture.md) for details and [docs/api-spec.md](./docs/api-spec.md) for the Go API spec.

## Project Structure

```
app/
  page.tsx                    # Landing page with search
  layout.tsx                  # Root layout (theme, fonts, metadata)
  globals.css                 # Tailwind v4 + shadcn/ui CSS vars
  account/page.tsx            # User account page
  docs/                       # Documentation pages
    page.tsx                  # Docs index
    layout.tsx                # Docs layout with sidebar
    api/page.tsx              # API documentation
    architecture/             # Architecture docs (overview, database, data-flow)
    configuration/page.tsx    # Configuration guide
    self-hosting/page.tsx     # Self-hosting guide
  roadmap/page.tsx            # Visual roadmap page
components/
  ui/                         # shadcn/ui components (button, card, input, etc.)
  site-header.tsx             # Shared header with account dropdown
  account-dropdown.tsx        # Account menu dropdown
  domain-search-form.tsx      # Domain search input
  theme-provider.tsx          # next-themes provider
  theme-toggle.tsx            # Light/dark mode toggle
  roadmap-flowchart.tsx       # Visual roadmap chart
  docs/                       # Docs components (sidebar, architecture diagram)
lib/
  types/                      # Shared TypeScript types (DNS, WHOIS, availability, database)
  utils.ts                    # Utility functions
```

## Current Status

### Done

- [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
- [x] TypeScript type definitions (`lib/types/`) — DNS, WHOIS, availability, database models
- [x] Shared site header with account dropdown
- [x] Account page
- [x] Documentation pages (architecture, API, configuration, self-hosting)
- [x] Visual roadmap page

### TODO

See [ROADMAP.md](./ROADMAP.md) for the full phased build plan. Next up:

- [ ] Supabase schema + migrations + RLS
- [ ] Supabase client setup (`@supabase/ssr`)
- [ ] 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