Architecture

ft-configs-service manages configuration domains for the FT platform and publishes read-optimized snapshots for runtime consumers. Key facts to remember:

  1. Database is the source of truth.

  2. Hazelcast holds read snapshots and is never master.

  3. The service owns validation, audit, and snapshot publication. Use the diagrams below for onboarding, architecture review, and operational reasoning.

C4: Context

ft-configs-c4-context
SMTP is not a hard dependency. When email is unavailable or disabled via MAIL_MODE (offline mode), the service runs without it: secrets are returned in API responses and the deletion OTP is skipped. See Configuration — Delivery modes.

C4: Container (ft-configs-service)

ft-configs-c4-container

Component Boundaries (packages)

The codebase is split by responsibility. Use these boundaries when navigating or changing behavior.

  • Web/API layer: @RestController classes under com.friendly.ftconfigsservice.*. They map HTTP requests to use cases and perform request/response shaping.

  • Service layer: @Service classes that own transactions, validation, and domain invariants. This is where write flows and cache refreshes are coordinated.

  • Persistence layer: JpaRepository interfaces and custom queries. Entities live alongside their repositories and often use @EntityGraph to avoid N+1.

  • Cache publishers: domain-specific Hazelcast writers (e.g. TabViewCacheService, NorthboundConfigCacheService). They produce read models and publish them to Hazelcast.

  • Cross-cutting components: security filters, global exception handling, audit, environment snapshot.

The diagram below reflects the real package roots under com.friendly.ftconfigsservice (auth, useradmin, role, acs, angular, provisionportal, serviceapi, northbound, environment, audit, utils). It groups classes by bounded context instead of listing every controller/service class.

ft-configs-components

Write and Read Flows

ft-configs-write-read-flows

If you are auditing correctness, also see Caching Strategy and Runtime Behavior for known consistency gaps.

Invariants and Responsibilities

  • Database is the authoritative storage for configuration.

  • Hazelcast stores derived read snapshots (IMap/IList); it is not master data. Cache names and key types are documented in Cache Catalog.

  • Runtime consumers (ACS, Northbound API, Provision Portal, Service API, Angular Backend, others) read from Hazelcast directly and do not read from this service.

  • ft-configs-service is responsible for validation, audit trail, and publishing snapshots. It does not run Hazelcast members and does not serve runtime reads.

  • Snapshot refresh is triggered by write flows (CRUD/import/export) and by startup warm-up.

  • Intended consistency rule: publish snapshots after DB commit. Current gaps (some publishes happen inside transactions) are documented in Runtime Behavior.

Security

  • Authentication: JWT access token is read from HTTP-only cookie with Authorization: Bearer … fallback.

  • CSRF protection is enabled (cookie-based CSRF tokens).

  • Roles/authorities: VIEWER → configs.read, EDITOR → configs.read/configs.write, ADMIN → configs.read/configs.write/users.manage.

  • Public endpoints include /csrf, /environment/snapshot, auth endpoints, and /actuator/**. Domain reads require configs.read; writes require configs.write.

  • Runtime consumers that read Hazelcast bypass REST auth entirely; treat Hazelcast network access as a trust boundary. See Security for details.

Observability and Operations

  • Health and metrics: /configs-service/actuator/health, /configs-service/actuator/metrics, /configs-service/actuator/prometheus.

  • Track Hazelcast publish latency and client connectivity issues (see Performance).

  • Logs include audit events and security-related events; request correlation uses X-Request-Id (see Monitoring & Logs).

  • Hazelcast outages: some caches fail fast on startup, others disable themselves when Hazelcast is offline. Operational notes are in Troubleshooting.