pounce/memory-bank/systemPatterns.md

Pounce - System Patterns

Architecture

┌─────────────────┐      ┌────────────────────┐
│   Next.js App   │◀────▶│     FastAPI API     │
│   (Port 3000)   │      │     (Port 8000)     │
└─────────────────┘      └──────────┬─────────┘
                                    │
                    ┌───────────────┼────────────────┐
                    │               │                │
              ┌─────▼─────┐   ┌────▼────┐     ┌─────▼─────┐
              │ Postgres  │   │  Redis  │     │ External   │
              │ (primary) │   │ queue + │     │ I/O (DNS,  │
              └───────────┘   │ limiter │     │ WHOIS, HTTP│
                              └─────────┘     └───────────┘

Separate processes (recommended):
- API: `ENABLE_SCHEDULER=false`
- Scheduler: `python backend/run_scheduler.py`
- Worker: `arq app.jobs.worker.WorkerSettings`

Design Patterns

Backend

• Repository Pattern: Database operations abstracted through SQLAlchemy
• Service Layer: Business logic in /services (DomainChecker, AuthService)
• Dependency Injection: FastAPI's Depends() for DB sessions and auth
• Async First: All database and I/O operations are async

Frontend

• Component-Based: Reusable React components
• Global State: Zustand store for auth and domain state
• API Client: Centralized API calls in /lib/api.ts
• Server Components: Next.js 14 App Router with client components where needed

Authentication Flow

1. User registers → Creates user + free subscription
2. User logs in → Backend sets HttpOnly auth cookie (JWT inside cookie)
3. Frontend calls API with `credentials: 'include'`
4. Backend validates cookie → Returns user data
5. OAuth uses `state` + validated redirects, then sets cookie (no JWT in URL)

Domain Checking Strategy

1. Normalize domain (lowercase, remove protocol/www)
2. Quick DNS check (A + NS records)
3. Full WHOIS lookup for details
4. If WHOIS says available but DNS has records → Trust DNS
5. Store result and update domain status

Scheduler Pattern

APScheduler (AsyncIO mode) in separate scheduler process
    │
    ├── Domain checks (tier-based frequency)
    ├── TLD price scrape + change detection
    ├── Auction scrape + cleanup
    └── Health cache refresh (writes DomainHealthCache used by UI)

Database Models

User (1) ─────┬───── (N) Domain
              │
              └───── (1) Subscription

Domain (1) ────── (N) DomainCheck

API Response Patterns

• Success: JSON with data
• Error: {"detail": "error message"}
• Pagination: {items, total, page, per_page, pages}
• Auth errors: 401 Unauthorized
• Permission errors: 403 Forbidden