# Directory Structure

> How backend code is organized in this project.

---

## Overview

Backend code is centered in `backend/src` and follows a route-module layout under `v1/` with shared infrastructure in `core/`.

- **HTTP entry**: `backend/src/app.py` and `backend/src/v1/router.py`
- **Feature modules**: `backend/src/v1/<domain>/`
- **Cross-cutting infrastructure**: `backend/src/core/`
- **ORM models**: `backend/src/models/`
- **Shared/domain schemas**: `backend/src/schemas/`
- **Global/base service providers**: `backend/src/services/`
- **Migrations**: `backend/alembic/`
- **Tests**: `backend/tests/{unit,integration,e2e}`

---

## Directory Layout

```text
backend/
├── src/
│   ├── app.py
│   ├── core/
│   │   ├── config/
│   │   ├── db/
│   │   ├── http/
│   │   ├── logging/
│   │   └── taskiq/
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── v1/
│       ├── router.py
│       ├── auth/
│       ├── users/
│       ├── todo/
│       ├── schedule_items/
│       └── ...
├── alembic/
│   ├── env.py
│   └── versions/
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/
```

---

## Module Organization

Observed feature-module pattern (evidence from multiple `v1/*` modules):

1. `router.py` contains FastAPI routes and request/response wiring
2. `dependencies.py` contains DI providers
3. `service.py` contains business logic, authz checks, transaction boundaries
4. `repository.py` contains query/CRUD logic only
5. `schemas.py` contains API DTOs (Pydantic)

Real examples:

- `backend/src/v1/todo/{router.py,dependencies.py,service.py,repository.py,schemas.py}`
- `backend/src/v1/schedule_items/{router.py,dependencies.py,service.py,repository.py,schemas.py}`
- `backend/src/v1/friendships/{router.py,dependencies.py,service.py,repository.py,schemas.py}`

Cross-module composition examples:

- `backend/src/v1/router.py` includes all domain routers under `/api/v1`
- `backend/src/app.py` mounts the v1 router and global exception handlers
- `backend/src/v1/todo/dependencies.py` composes DB session + user dependency + repositories into `TodoService`

---

## Naming Conventions

Conventions observed in current codebase:

- Package and file names use **snake_case** (`schedule_items`, `inbox_messages`, `registration_bootstrap.py`)
- Route package names are domain nouns (`todo`, `users`, `auth`, `agent`)
- Common file names are stable across modules:
  - `router.py`
  - `service.py`
  - `repository.py`
  - `schemas.py`
  - `dependencies.py`
- Logger names usually follow module path semantics, e.g.:
  - `get_logger("v1.todo.service")`
  - `get_logger("v1.schedule_items.repository")`
  - `get_logger("api.app")`

---

## Anti-patterns / Forbidden Patterns

Grounded by repository rules and existing structure:

- Do not place backend feature code under `apps/**` or non-backend folders; backend runtime code stays in `backend/src/**`.
- Do not bypass module layering by putting SQL and transaction commits directly in router files.
  - Current positive references: `backend/src/v1/todo/router.py` (routing only), `backend/src/v1/todo/service.py` (commit/rollback), `backend/src/v1/todo/repository.py` (query layer).
- Do not introduce ad-hoc folder layouts for new domains when `v1/<domain>/{router,service,repository,schemas,dependencies}` already exists.

---

## Uncertainties (documented, not invented)

- There is no explicit convention doc yet for when logic should go to `backend/src/services/**` versus `backend/src/v1/**`; both exist and are currently used for different scopes.
- `backend/src/v1/analytics/` includes `tasks.py` and static web content usage from `backend/src/app.py` (`v1/analytics/web`), which is slightly different from CRUD-oriented modules.