ArchitectureAdrADR 0008: Minimal Ports and Adapters

ADR 0008: Minimal Ports and Adapters

ADR 0008: Minimal Ports and Adapters

Status

Accepted

Context

Jorvis has grown in scope (graph nodes, tools, providers). Testing and provider swaps are harder without clear seams. A full clean-architecture rewrite would be high risk and slow.

Decision

Adopt a minimal ports/adapters pattern for only the highest-churn boundaries:

  • AI provider access
  • Query execution
  • Audit storage
  • Schema metadata access
  • Optional cache port for schema metadata (e.g., LRU)

This is an incremental refactor, not a full layered rewrite.

Priority Order

  1. AI provider access
  2. Query execution
  3. Audit storage
  4. Schema metadata access
  5. Optional cache port (only if performance data justifies it)

Constraints

  • Keep current NestJS module boundaries intact.
  • Use DI tokens/abstract classes for ports.
  • Avoid cross-module cycles; adapters only depend on port interfaces.

Consequences

  • Better testability and mocking for core boundaries.
  • Lower risk than a full clean-architecture migration.
  • Some duplication during transition period.

Alternatives

  • Full clean-architecture rewrite (rejected: high risk).
  • Status quo (rejected: testability and provider coupling issues).

DoD / Evidence

  • Ports introduced for AI provider and query execution.
  • Existing flows still pass tests without behavior changes.