pounce/memory-bank/techContext.md

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

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

Frontend

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