Identity & Access Context: Architecture & Implementation Guide
1. Domain Overview The Identity & Access Context is the gateway to the Echo platform.
Operating as a strictly isolated bounded context within our Modular Monolith, it is exclusively
responsible for user provisioning, authentication, session management, and credential security. It
is entirely isolated from catalog and streaming logic.
Core Responsibilities:




Authentication: Securely validating credentials and minting stateless JWT access tokens
for the global security filter.
Session Management: Issuing, tracking, and revoking stateful Refresh Tokens to support
persistent logins across multiple Flutter clients (e.g., mobile and web simultaneously).
Provisioning: Securely registering new users, hashing passwords via Bcrypt, and
handling basic profile metadata.
Telemetry Emission: Publishing standard authentication events to the Kafka broker for
downstream data engineering ingestion.
2. Domain Model (Inner Core) This layer enforces pure business rules without any framework
dependencies.



Value Objects: Self-validating immutable records. Includes concepts like Email Address
(which validates format upon creation), Password Hash (which ensures raw strings never
leak), and Device Fingerprint (which parses OS and device details).
Entities & Aggregate Root: The "User" is the Aggregate Root. It gatekeeps all state
changes. The "Device Session" is a child entity tracked within the User aggregate,
containing the refresh token data and expiration dates.
Domain Ports (Interfaces): Defines the required contracts for the infrastructure layer to
implement. Includes the User Repository (database access), Token Generator (JWT
minting), and Auth Event Publisher (Kafka routing).
3. Infrastructure (Outer Core) This layer binds the pure domain to our specific tech stack.


Database Schema: Managed via version-controlled migrations. Tables are explicitly
prefixed (e.g., identity_users, identity_sessions) to enforce module isolation. The sessions
table maintains a strict foreign key relationship to the user table.
Kafka Telemetry Contract: A strictly formatted data payload emitted upon
authentication events. It captures the event ID, user ID, event type, timestamp, IP
address, user agent, and parsed device metadata to feed the Medallion Architecture.
4. API Contract (Flutter Integration)


POST /api/v1/auth/register: Creates a new user profile and returns the initial JWT and
Refresh Token.
POST /api/v1/auth/login: Validates user credentials, registers a new device session, and
returns tokens.



POST /api/v1/auth/refresh: Accepts a valid Refresh Token to seamlessly mint a new
JWT Access Token for the mobile client.
GET /api/v1/auth/devices: Retrieves a list of all active device sessions for the
authenticated user.
DELETE /api/v1/auth/devices/{id}: Revokes a specific device session, enabling the
user to log out of specific devices remotely.
Dependencies Needed for JWT Token
jjwt-jackson
jjwt-api
jjwt-impl