# Pounce - Technical Context

## Tech Stack

### Backend
- **Framework:** FastAPI (Python 3.11+)
- **Database:** SQLite (development) / PostgreSQL (production)
- **ORM:** SQLAlchemy 2.0 with async support
- **Authentication:** HttpOnly cookie auth (JWT in cookie) + OAuth (Google/GitHub)
- **Scheduling:** APScheduler (recommended as separate scheduler process)
- **Job Queue (optional):** Redis + ARQ worker for non-blocking admin/long jobs
- **Observability:** Prometheus metrics endpoint (`/metrics`)

### Frontend
- **Framework:** Next.js 14 (App Router)
- **Styling:** Tailwind CSS
- **State Management:** Zustand
- **Icons:** Lucide React (outlined icons)

### Domain Checking
- **WHOIS:** python-whois library
- **DNS:** dnspython library
- No external APIs required

## Project Structure

```
hushen_test/
├── backend/
│   ├── app/
│   │   ├── api/           # API endpoints
│   │   ├── models/        # Database models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── services/      # Business logic
│   │   ├── jobs/          # ARQ worker + tasks (optional)
│   │   ├── observability/ # Metrics (Prometheus)
│   │   ├── config.py      # Settings
│   │   ├── database.py    # DB configuration
│   │   ├── main.py        # FastAPI app
│   │   └── scheduler.py   # Background jobs
│   ├── requirements.txt
│   └── run.py
├── frontend/
│   ├── src/
│   │   ├── app/           # Next.js pages
│   │   ├── components/    # React components
│   │   └── lib/           # Utilities
│   └── package.json
└── memory-bank/           # Project documentation
```

## API Endpoints (high-level)

### Public
- `POST /api/v1/check/` - Check domain availability
- `GET /api/v1/check/{domain}` - Quick domain check

### Authenticated
- `POST /api/v1/auth/register` - Register user
- `POST /api/v1/auth/login` - Sets HttpOnly cookie session
- `GET /api/v1/auth/me` - Current user info
- `GET /api/v1/domains/` - List monitored domains
- `GET /api/v1/domains/health-cache` - Bulk cached health reports for watchlist UI
- `POST /api/v1/domains/` - Add domain to watchlist
- `DELETE /api/v1/domains/{id}` - Remove domain
- `POST /api/v1/domains/{id}/refresh` - Manual refresh
- `GET /api/v1/subscription/` - User subscription info
- `GET /api/v1/subscription/tiers` - Available plans
- `GET /api/v1/dashboard/summary` - Single-call payload for `/terminal/radar`

## Development

### Backend
```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run.py
```

### Frontend
```bash
cd frontend
npm install
npm run dev
```

## Production Deployment
- Backend: run API + scheduler (separate) + optional worker
- Frontend: Next.js (`output: 'standalone'` for Docker)
- Database: PostgreSQL recommended
- Redis: recommended (rate limiting storage + job queue)
- Reverse proxy: nginx recommended