113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
|
# 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.
|