# 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)

## Update (2026-05-04)

The vertical-feature refactor preserved InversifyJS but moved from a single shared container in `packages/core/src/di/` to **per-feature containers** in each feature package (`packages/<feature>/src/di/container.ts`). See ADR-008.