pounce/README.md

# 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

```bash
git clone <your-repo-url>
cd pounce
```

### 2. Backend Setup

```bash
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:

```env
# 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:

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

# Or use the run script
python run.py
```

### 3. Frontend Setup

```bash
cd frontend

# Install dependencies
npm install

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

Start the frontend:

```bash
# 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`:

```ini
[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:

```bash
sudo systemctl enable pounce-backend
sudo systemctl start pounce-backend
```

#### Option B: Docker

```dockerfile
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)

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

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

```nginx
# /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):

```bash
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:

```bash
sudo apt install postgresql postgresql-contrib
```

2. Create database:

```bash
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`:

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

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

```bash
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.