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:
2026-04-29 20:25:25 +02:00
parent b6631b86e4
commit 9a43123b3a
3 changed files with 195 additions and 10 deletions

View File

@@ -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