# folio-org/folio-module-sidecar architecture

> Architecture diagram of the GitHub repository folio-org/folio-module-sidecar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/folio-org/folio-module-sidecar
- Repository: https://github.com/folio-org/folio-module-sidecar

## Overview

##### Main Components
- Sidecar Application (the core Quarkus application)
- That it implements both inbound (Ingress) and outbound (Egress) routing.
- That it handles security (JWT validation, Keycloak integrations), performs health checks, and hosts a configurable routing mechanism.
- Underlying Module (specified by environment variables such as MODULE_URL, MODULE_NAME, MODULE_VERSION)
- Target module that the sidecar routes requests to.
- External Integrations
- Okapi and its role in module configuration (obtaining Module Descriptors).
- Authentication and Token Management: Keycloak for JWT validation, token introspection, impersonation, and authorization.
- Manager services: integration with mgr-applications (AM), mgr-tenant-entitlements (TE), mgr-tenants (TM) for bootstrap/discovery.
- Secure storage: abstract integration for AWS SSM or Vault for secure credential storage.
- Kafka: components consuming discovery, logout, tenant entitlement, and other events.

##### Architectural Interactions
- Ingress Flow:
- Path transformation or header enrichment: illustrate extraction of a tenant or user ID to add to HTTP headers.
- Forward request to the “Underlying Module”.
- Egress Flow:
- That it retrieves credentials from the “Credential Service” (with subcomponents for asynchronous secure store access).
- Communication to external systems such as Keycloak (for service accounts) and potentially to an API Gateway (if forwarding unknown requests).
- Event/Discovery Flow:
- Kafka integrations: components like DiscoveryConsumer, TenantEntitlementConsumer, and LogoutConsumer.
- How they listen for events and update the dynamic routing configurations.
- Health and Monitoring:
- A “Health Check” component that periodically verifies the status of the sidecar, including health utilities and route validation.

##### Architectural Patterns and Principles
- Microservice Architecture – showing the sidecar as a thin intermediary separating the underlying module from direct traffic.
- Configurable Routing – dynamic discovery and cache updates using event consumers and lookup mechanisms.
- Integration of multiple clients (HTTP clients for Keycloak, Okapi, and manager components), using properties and configuration classes for these dependencies.

##### Relevant Technologies and Frameworks
- Quarkus: as the application framework powering the module with live reload, native compile capabilities, and production build options.
- Maven: as the build tool (if needed, can be annotated in a “Build & Deployment” section).
- Docker and containerization: for running both JVM-based and native versions, as well as FIPS compliant builds.
- Kafka: for asynchronous event processing.
- Keycloak: for authentication and authorization duties.
- Secure Storage Options: AWS SSM/Vault indicated by the secure store configurations.
- Optional integration with Okapi module descriptors and FOLIO’s ecosystem.

##### Elements
- Clear labels for each component (e.g., Ingress Handler, Egress Handler, Credential Service, Health Check, Dynamic Routing Lookup).
- From clients to Ingress Handler, then to Underlying Module after security checks.
- From Sidecar to external Keycloak server for token exchanges.
- From Sidecar to Kafka consumers for configuration updates.
- Feedback loops (e.g., caching mechanisms or health check triggers).
- Another group for external integrations (Keycloak, manager services, Okapi, secure store, API gateway).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    EC["External Client"]:::external
    UM["Underlying Module"]:::external
    EK["Keycloak (External)"]:::external
    AG["API Gateway"]:::external
    SS["Secure Storage"]:::external
    Okapi["Okapi"]:::external

    %% Kafka Integration Subgraph (External)
    subgraph "Kafka Integration"
        direction TB
        DCons["Discovery Consumer"]:::external
        LCons["Logout Consumer"]:::external
        TCons["Tenant Entitlement Consumer"]:::external
    end

    %% Manager Services Subgraph (External)
    subgraph "Manager Services"
        direction TB
        AM["Application Manager"]:::external
        TM["Tenant Manager"]:::external
        TES["Tenant Entitlement Service"]:::external
    end

    %% Internal Components: Folio Module Sidecar
    subgraph "Folio Module Sidecar"
        direction TB
        SA["Sidecar Application"]:::internal
        IH["Ingress Request Handler"]:::internal
        JWT["JWT Parser & Filter"]:::internal
        KI["Keycloak Integration"]:::internal
        EH["Egress Request Handler"]:::internal
        CS["Credential Service"]:::internal
        ASS["Async Secure Store"]:::internal
        DR["Dynamic Routing Lookup"]:::internal
        HC["Health Check"]:::internal
        IC["Integration Clients"]:::internal
        SA --> IH
    end

    %% Ingress Flow
    EC --> IH
    IH --> JWT
    JWT --> KI
    KI --> UM
    KI --> Okapi

    %% Egress Flow
    EH --> CS
    CS --> ASS
    CS --> AG
    EH --> EK

    %% Dynamic Routing & Kafka Integration
    DCons -->|"updates"| DR
    LCons -->|"updates"| DR
    TCons -->|"updates"| DR
    DR --> IH
    DR --> IC

    %% Health Check Monitoring
    HC -.-> IH
    HC -.-> EH
    HC -.-> DR

    %% Manager Services Integration Flow
    IC --> AM
    IC --> TM
    IC --> TES

    %% Secure Storage Flow
    ASS --> SS

    %% Click Events for Internal Components
    click SA "https://github.com/folio-org/folio-module-sidecar/tree/master/src/main/java/org/folio/sidecar"
    click IH "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/service/routing/handler/IngressRequestHandler.java"
    click EH "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/service/routing/handler/EgressRequestHandler.java"
    click JWT "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/service/auth/JwtParserProvider.java"
    click KI "https://github.com/folio-org/folio-module-sidecar/tree/master/src/main/java/org/folio/sidecar/integration/keycloak"
    click UM "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/configuration/properties/ModuleProperties.java"
    click CS "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/integration/cred/CredentialService.java"
    click ASS "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/integration/cred/store/AsyncSecureStore.java"
    click DR "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/service/routing/lookup/DynamicRoutingLookup.java"
    click HC "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/health/ModuleHealthCheck.java"

    %% Click Events for Kafka Integration
    click DCons "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/integration/kafka/DiscoveryConsumer.java"
    click LCons "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/integration/kafka/LogoutConsumer.java"
    click TCons "https://github.com/folio-org/folio-module-sidecar/blob/master/src/main/java/org/folio/sidecar/integration/kafka/TenantEntitlementConsumer.java"

    %% Click Events for Manager Services Integration
    click AM "https://github.com/folio-org/folio-module-sidecar/tree/master/src/main/java/org/folio/sidecar/integration/am"
    click TM "https://github.com/folio-org/folio-module-sidecar/tree/master/src/main/java/org/folio/sidecar/integration/tm"
    click TES "https://github.com/folio-org/folio-module-sidecar/tree/master/src/main/java/org/folio/sidecar/integration/te"

    %% Styles
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#f99,stroke:#933,stroke-width:2px;
```
