as4-411/docs/adr/001-persistence-caching.md

ADR-001: Persistence and Caching Strategy

Status

Accepted.

Context

as4-411 needs canonical persistence for directory data (tenants, participants, identifiers, endpoints, capabilities, credentials, policies) and a caching strategy for resolution results to support low-latency gateway lookups and resilience.

Decision

Persistence

• Primary store: PostgreSQL. Chosen for ACID guarantees, relational model matching the data model, and operational familiarity (replication, backups, tooling).
• Migrations: SQL migrations live under packages/storage/migrations/ (e.g. 001_initial.sql). Applied out-of-band or via a migration runner; no automatic migrate on startup by default.
• Alternatives: In-memory store for development and tests; SQLite for embedded/library deployments where Postgres is not available. Both implement the same DirectoryStore/AdminStore port.

Caching

• Resolution cache: In-process TTL cache (e.g. InMemoryResolveCache) keyed by canonical ResolveRequest (identifiers, serviceContext, constraints, tenant). Positive and negative results are cached; negative TTL is shorter (e.g. 60s) to avoid prolonged stale “not found.”
• Cache key: Deterministic and stable for same inputs (see ADR-002).
• Invalidation: On directory mutation (participant/identifier/endpoint/policy change), invalidate by tenant or by cache key prefix when a proper event or hook is available; until then, rely on TTL.
• Optional: Redis or similar for shared cache across multiple resolver instances; same interface ResolveCache.

Consequences

• Gateways can rely on Postgres for durability and use in-memory or Redis cache for latency.
• Embedded use cases can use SQLite or in-memory without Postgres dependency.