Why
The service currently uses in-memory state for users, refresh sessions, lockouts, and rate limits. This makes restarts destructive and prevents safe horizontal scaling.
Proposal
Introduce a storage abstraction layer with production-ready adapters:
UserRepository (create/find/update/delete)
SessionRepository (refresh token family tracking, revoke one/all)
SecurityRepository (lockout counters, rate-limit windows, token denylist)
Implement two concrete adapters:
- PostgreSQL for users + durable session metadata
- Redis for ephemeral security state (lockouts, rate limits, short-lived denylist/TTL)
Scope
- Keep current in-memory implementation as a
MemoryAdapter for dev/tests
- Add config-based adapter selection (
MEMORY vs POSTGRES_REDIS)
- Add migration strategy and seed script for local dev
- Ensure existing API contracts remain backward-compatible
API/Behavior Changes
- No breaking endpoint changes
- Existing semantics for refresh rotation/logout-all remain intact across process restarts
Technical Notes
- Add DB schema for users, refresh session families, and session revocation metadata
- Use transaction boundaries for login/refresh/revoke flows to avoid race conditions
- Add integration tests for multi-instance behavior and restart durability
Acceptance Criteria
- Users/sessions persist across restarts
logout-all revokes all active sessions consistently across instances
- Lockout/rate-limit state is shared across instances
- Test suite includes adapter-contract tests and integration coverage
- Documentation updated with local + production setup steps
Out of Scope
- Full multi-tenant architecture
- Third-party identity providers
Why
The service currently uses in-memory state for users, refresh sessions, lockouts, and rate limits. This makes restarts destructive and prevents safe horizontal scaling.
Proposal
Introduce a storage abstraction layer with production-ready adapters:
UserRepository(create/find/update/delete)SessionRepository(refresh token family tracking, revoke one/all)SecurityRepository(lockout counters, rate-limit windows, token denylist)Implement two concrete adapters:
Scope
MemoryAdapterfor dev/testsMEMORYvsPOSTGRES_REDIS)API/Behavior Changes
Technical Notes
Acceptance Criteria
logout-allrevokes all active sessions consistently across instancesOut of Scope