pounce — Domain Availability Monitoring

A full-stack application for monitoring domain name availability with TLD price tracking.

Tech Stack

Backend

• Python 3.12+
• FastAPI — Modern async web framework
• SQLAlchemy 2.0 — Async ORM
• SQLite (dev) / PostgreSQL (production)
• APScheduler — Background job scheduling
• python-whois & whodap — Domain availability checking (WHOIS + RDAP)

Frontend

• Next.js 14 — React framework with App Router
• TypeScript
• Tailwind CSS — Styling
• Zustand — State management
• Lucide React — Icons

---

Project Structure

pounce/
├── backend/
│   ├── app/
│   │   ├── api/           # API endpoints
│   │   ├── models/        # SQLAlchemy models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── services/      # Business logic
│   │   ├── config.py      # Settings
│   │   ├── database.py    # DB connection
│   │   ├── main.py        # FastAPI app
│   │   └── scheduler.py   # Background jobs
│   ├── requirements.txt
│   └── run.py
├── frontend/
│   ├── src/
│   │   ├── app/           # Next.js pages
│   │   ├── components/    # React components
│   │   └── lib/           # Utilities & API client
│   ├── package.json
│   └── tailwind.config.ts
└── README.md

---

Installation

Prerequisites

• Python 3.12+
• Node.js 18+
• npm or yarn

1. Clone the Repository

git clone <your-repo-url>
cd pounce

2. Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/macOS
# or
.\venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Create environment file
cp env.example.txt .env

Edit .env with your settings:

# Database
DATABASE_URL=sqlite+aiosqlite:///./domainwatch.db

# Security - CHANGE THIS IN PRODUCTION!
SECRET_KEY=your-super-secret-key-change-in-production-min-32-chars

# CORS
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

# Optional: Email notifications
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USER=your-email@example.com
# SMTP_PASSWORD=your-password

Start the backend:

# Development
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Or use the run script
python run.py

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Create environment file
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

Start the frontend:

# Development
npm run dev

# Production build
npm run build
npm start

---

Production Deployment

Backend (Python/FastAPI)

Option A: Systemd Service (Linux)

1. Create service file /etc/systemd/system/pounce-backend.service:

[Unit]
Description=pounce Backend API
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/pounce/backend
Environment="PATH=/var/www/pounce/backend/venv/bin"
ExecStart=/var/www/pounce/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

2. Enable and start:

sudo systemctl enable pounce-backend
sudo systemctl start pounce-backend

Option B: Docker

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Frontend (Next.js)

Option A: PM2 (Node.js)

cd frontend
npm run build

# Install PM2 globally
npm install -g pm2

# Start with PM2
pm2 start npm --name "pounce-frontend" -- start

# Save PM2 config
pm2 save
pm2 startup

Option B: Docker

FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app

ENV NODE_ENV production

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000

CMD ["node", "server.js"]

Nginx Reverse Proxy

# /etc/nginx/sites-available/pounce

server {
    listen 80;
    server_name yourdomain.com;

    # Frontend
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # Backend API
    location /api {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable with SSL (Let's Encrypt):

sudo ln -s /etc/nginx/sites-available/pounce /etc/nginx/sites-enabled/
sudo certbot --nginx -d yourdomain.com
sudo systemctl reload nginx

---

Environment Variables

Backend (.env)

Variable	Description	Default
DATABASE_URL	Database connection string	sqlite+aiosqlite:///./domainwatch.db
SECRET_KEY	JWT signing key (min 32 chars)	Required
CORS_ORIGINS	Allowed origins (comma-separated)	http://localhost:3000
SMTP_HOST	Email server host	Optional
SMTP_PORT	Email server port	587
SMTP_USER	Email username	Optional
SMTP_PASSWORD	Email password	Optional

Frontend (.env.local)

Variable	Description	Default
NEXT_PUBLIC_API_URL	Backend API URL	http://localhost:8000

---

Database

Development (SQLite)

SQLite is used by default. The database file domainwatch.db is created automatically.

Production (PostgreSQL)

1. Install PostgreSQL:

sudo apt install postgresql postgresql-contrib

2. Create database:

sudo -u postgres psql
CREATE DATABASE pounce;
CREATE USER pounce_user WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE pounce TO pounce_user;
\q

3. Update .env:

DATABASE_URL=postgresql+asyncpg://pounce_user:your-password@localhost:5432/pounce

---

API Endpoints

Authentication

• POST /api/v1/auth/register — Register new user
• POST /api/v1/auth/login — Login and get JWT token
• GET /api/v1/auth/me — Get current user

Domains

• POST /api/v1/check — Check domain availability
• GET /api/v1/domains — List monitored domains
• POST /api/v1/domains — Add domain to watchlist
• DELETE /api/v1/domains/{id} — Remove domain

TLD Prices

• GET /api/v1/tld-prices/overview — Get TLD overview
• GET /api/v1/tld-prices/trending — Get trending TLDs
• GET /api/v1/tld-prices/{tld} — Get TLD details

Admin

• GET /api/v1/admin/users — List all users
• PUT /api/v1/admin/users/{id} — Update user

---

Features

Subscription Tiers

Feature	Starter (Free)	Professional	Enterprise
Domains	3	25	100
Check Frequency	Daily	Daily	Hourly
Alerts	Email	Priority	Priority
WHOIS Data	Basic	Full	Full
History	—	30 days	Unlimited
API Access	—	—	✓

Domain Checking

• RDAP (primary) — Modern protocol with detailed data
• WHOIS (fallback) — Traditional protocol
• DNS (quick check) — Fast availability check

---

Development

Backend

cd backend
source venv/bin/activate

# Run with auto-reload
uvicorn app.main:app --reload

# API docs available at:
# http://localhost:8000/docs (Swagger)
# http://localhost:8000/redoc (ReDoc)

Frontend

cd frontend

# Development server
npm run dev

# Lint
npm run lint

# Build
npm run build

---

Troubleshooting

Backend won't start

1. Check Python version: python3 --version (needs 3.12+)
2. Ensure virtual environment is activated
3. Check .env file exists and has valid SECRET_KEY

Frontend can't connect to backend

1. Ensure backend is running on port 8000
2. Check NEXT_PUBLIC_API_URL in .env.local
3. Verify CORS origins in backend .env

Database errors

1. Delete domainwatch.db to reset (dev only)
2. Check database URL format in .env

---

License

MIT License

---

Support

For issues and feature requests, please open a GitHub issue.