Backend Structure
=================

The backend follows a clean layered architecture within the
``backend/backend/`` directory.

Directory Layout
-----------------

.. code-block:: text

   backend/
   ├── pyproject.toml          # Project metadata & dependencies
   ├── dockerfile              # Multi-stage Docker build
   ├── backend/
   │   ├── __init__.py
   │   ├── dependencies.py     # FastAPI dependency injection (auth, DB)
   │   ├── permissions.py      # Permission decorators & role checks
   │   ├── api/
   │   │   ├── main.py         # FastAPI app factory & lifespan
   │   │   ├── routers/        # HTTP route handlers
   │   │   │   ├── project.py
   │   │   │   ├── threads.py
   │   │   │   ├── resources.py
   │   │   │   ├── form_templates.py
   │   │   │   ├── initial_diagnosis.py
   │   │   │   └── users.py
   │   │   └── schemas/        # Pydantic request/response models
   │   ├── database/
   │   │   ├── database.py     # Engine & session factory
   │   │   └── repositories/   # Generic CRUD repositories
   │   ├── models/             # SQLAlchemy ORM models
   │   │   ├── project.py
   │   │   ├── user.py
   │   │   ├── template_instance.py
   │   │   ├── templates_phase1.py
   │   │   ├── templates_phase2.py
   │   │   ├── templates_phase3.py
   │   │   └── templates_phase4.py
   │   ├── service/            # Business logic
   │   │   ├── project/
   │   │   ├── template/
   │   │   ├── user/
   │   │   ├── chat/           # AI orchestrator & agents
   │   │   ├── initial_diagnosis/
   │   │   ├── form_templates/
   │   │   ├── pdf/
   │   │   └── project_maturity/
   │   ├── utils/              # Shared utilities
   │   └── tests/              # Test suite
   └── migrations/             # Alembic database migrations

Layer Responsibilities
-----------------------

API Layer (``api/``)
~~~~~~~~~~~~~~~~~~~~~

- **Routers:** Define HTTP endpoints, parse request parameters, return responses
- **Schemas:** Pydantic models for request validation and response serialization
- **Main:** Application factory, lifespan hooks, middleware setup

Service Layer (``service/``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Contains all business logic
- Orchestrates repository calls
- Handles LLM integration, template generation, notifications
- Each service is a class with async methods

Repository Layer (``database/repositories/``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Generic base class with CRUD operations
- One repository per model type
- Async SQLAlchemy sessions
- No business logic — pure data access

Models (``models/``)
~~~~~~~~~~~~~~~~~~~~~

- SQLAlchemy ORM declarative models
- Define table schemas, relationships, constraints
- Organized by phase (templates_phase1.py, etc.)

Key Patterns
-------------

**App Lifespan:**

.. code-block:: python

   @asynccontextmanager
   async def lifespan(app: FastAPI):
       # Startup: DB init, orchestrator setup
       await init_database()
       await init_orchestrator()
       yield
       # Shutdown: cleanup

**Dependency Injection:**

.. code-block:: python

   @router.get("/projects")
   async def list_projects(
       user_id: str = Depends(get_current_user_id),
       db: AsyncSession = Depends(get_db),
   ):
       ...

**Repository Usage:**

.. code-block:: python

   class ProjectService:
       def __init__(self, db: AsyncSession):
           self.repo = ProjectRepository(db)

       async def create(self, data: ProjectCreate) -> Project:
           project = Project(**data.dict())
           return await self.repo.create(project)