# System Design

## High-level design

The API uses a layered architecture:

1. **Routers / Controllers**
   Handle HTTP transport, request parsing, auth dependencies, and response envelopes.
2. **Services**
   Contain business rules such as relationship management, auth decisions, and bulk orchestration.
3. **Repositories**
   Encapsulate data access, filtering, search, sorting, and cursor pagination logic.
4. **Models**
   SQLAlchemy entities describing the persistence schema.
5. **Schemas**
   Pydantic models for validated request and response contracts.

## Domain entities

- `users`
- `companies`
- `contacts`
- `contact_company_links`
- `interactions`

## Extensibility hooks

This structure is designed so that future domains can be added as parallel modules:

- `deals`
- `pipelines`
- `campaigns`
- `timelines`
- `webhooks`
- `integrations`

Each new domain should get:

- model
- schema
- repository
- service
- versioned router

## Security model

- JWT bearer authentication
- role-aware dependencies (`user`, `admin`)
- centralized API error handling
- rate limiting middleware
- versioned API namespace

## Scaling approach

When traffic grows:

- move from SQLite to PostgreSQL
- move rate limiting to Redis
- add background workers for emails/webhooks
- introduce read models for search-heavy use cases
- add audit/event tables for timelines and external sync