System Overview
===============

The Co-design Platform follows a layered architecture with clear separation
of concerns.

Design Principles
------------------

**Async-First:**
   All I/O operations (database, LLM calls, vector search) are async using
   Python's ``asyncio``, ``asyncpg``, and ``SQLAlchemy 2.0`` async sessions.

**Repository Pattern:**
   Data access is abstracted behind generic repository interfaces, making it
   easy to swap implementations (e.g., SQLAlchemy → MongoDB).

**Service Layer Abstraction:**
   Business logic lives in service classes, not in routers. Routers handle only
   HTTP protocol concerns.

**Dependency Injection:**
   FastAPI's built-in DI system provides database sessions, authenticated users,
   and service instances to route handlers.

**Singleton Services:**
   Heavy resources (embedding models, vector DB connections, orchestrator) are
   initialized once and shared across requests.

Request Flow
-------------

A typical API request flows through:

.. code-block:: text

   1. HTTP Request
   2. FastAPI Middleware (CORS, exception handling)
   3. Route Handler (router function)
   4. Dependency Injection (auth, DB session, services)
   5. Service Layer (business logic)
   6. Repository Layer (data access)
   7. Database (PostgreSQL / Weaviate / LLM)
   8. Response serialization (Pydantic schema)
   9. HTTP Response

Network Topology
-----------------

Docker Compose creates two networks:

- **internal** (``codesign-${ENV}-internal``): Backend ↔ PostgreSQL ↔ LiteLLM ↔ Neo4j
- **codesign-shared** (external): Shared services (Weaviate, SearXNG, Crawl4AI)

Only the backend and LiteLLM expose ports to the host machine.