social-app/.trellis/spec/backend/directory-structure.md

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

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.