docs: Define explicit DI container strategy for backend service graph
- Add comprehensive 'Dependency Wiring and Service Composition' section to Architekture.md (§ 2.3) documenting: * The lightweight FastAPI Depends() pattern used as composition root * Service composition through explicit parameter passing * Service context dependencies pattern (SessionServiceContext, etc.) * Repository boundary enforcement * Lifecycle and scope management * Checklist for adding new services - Update Backend-Development.md to reference the new Architecture section from the 'Dependency Layering' section - Enhance dependencies.py module docstring with clear explanation of: * Composition root pattern * Explicit over implicit principles * Service context dependencies * Repository boundary enforcement This resolves issue #39 by providing clear guidance on dependency wiring without over-engineering. The pattern uses FastAPI's built-in Depends() framework and avoids heavyweight container libraries, keeping the solution lightweight and maintainable. Fixes: #39 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -1,14 +1,32 @@
|
||||
"""FastAPI dependency providers.
|
||||
"""FastAPI dependency providers and composition root.
|
||||
|
||||
All ``Depends()`` callables that inject shared resources (database
|
||||
connection, settings, services, auth guard) are defined here.
|
||||
Routers import directly from this module — never from ``app.state``
|
||||
directly — to keep coupling explicit and testable.
|
||||
This module is BanGUI's dependency injection composition root. All injectable
|
||||
resources — database connections, settings, services, repositories, and
|
||||
authentication guards — are defined here as provider functions.
|
||||
|
||||
IMPORTANT: Routers should depend on repository dependencies (e.g., SessionRepoDep,
|
||||
BlocklistRepositoryDep) rather than on database connections. This enforces the
|
||||
repository boundary: only repositories and services access the database directly.
|
||||
See Backend-Development.md § 6 for the dependency layering rules.
|
||||
**Key Principles:**
|
||||
|
||||
1. **Composition Root Pattern**: No heavyweight DI container is used. Instead,
|
||||
FastAPI's `Depends()` framework manages all dependencies, keeping the pattern
|
||||
lightweight and explicit.
|
||||
|
||||
2. **Explicit Over Implicit**: Every dependency is declared in function signatures.
|
||||
There is no hidden coupling or magic. This makes the dependency graph visible
|
||||
to type checkers, debuggers, and developers.
|
||||
|
||||
3. **Service Context Dependencies**: Related resources (e.g., db + repository) are
|
||||
bundled into context objects (SessionServiceContext, BlocklistServiceContext)
|
||||
to prevent routers from accessing raw database connections.
|
||||
|
||||
4. **Repository Boundary Enforcement**: Routers must NOT import DbDep. They depend
|
||||
on service context dependencies instead, which contain both the database
|
||||
connection and the necessary repositories. This ensures repositories are the
|
||||
only modules executing SQL.
|
||||
|
||||
See Architekture.md § 2.3 (Dependency Wiring and Service Composition) for a
|
||||
complete guide to the DI pattern, including examples of adding new services.
|
||||
|
||||
See Backend-Development.md § 6 for dependency layering rules.
|
||||
"""
|
||||
|
||||
import datetime
|
||||
|
||||
Reference in New Issue
Block a user