agentic-dev-template/docs/decisions/adr-002-di-framework.md

ADR-002: InversifyJS for Dependency Injection

Status: Accepted

Context

Need DI for clean architecture. Options: InversifyJS, tsyringe, manual composition root.

Decision

InversifyJS with symbol-based resolution + targeted agent documentation.

Rationale

• Scales to 20+ services with automatic dependency chain resolution
• Built-in singleton/transient/request scopes
• Middleware support for logging/tracing (Sentry integration)
• Matches the reference implementation by Lazar Nikolov
• Agent readability gap (4/10 → 7/10) mitigated by resolution tables and step-by-step recipes in di/AGENTS.md
• Familiar to developers from Java/C# backgrounds

Trade-offs

• Requires reflect-metadata + decorator config in tsconfig
• Symbol indirection harder to trace than plain functions
• Extra dependency (inversify + reflect-metadata)