pounce/memory-bank/systemPatterns.md

DomainWatch - System Patterns

Architecture

┌─────────────────┐     ┌─────────────────┐
│   Next.js App   │────▶│  FastAPI Backend │
│   (Port 3000)   │◀────│   (Port 8000)    │
└─────────────────┘     └────────┬────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
              ┌─────▼─────┐ ┌────▼────┐ ┌────▼────┐
              │  SQLite/  │ │  WHOIS  │ │   DNS   │
              │  Postgres │ │ Lookups │ │ Lookups │
              └───────────┘ └─────────┘ └─────────┘

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 → Receives JWT token
3. Token stored in localStorage
4. API requests include Bearer token
5. Backend validates token → Returns user data

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)
    │
    └── CronTrigger (daily at 06:00)
            │
            └── check_all_domains()
                    │
                    ├── Fetch all domains
                    ├── Check each with 0.5s delay
                    ├── Update statuses
                    └── Log newly available domains

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