# 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

