# kea-renov8/befly-gateway architecture

> Architecture diagram of the GitHub repository kea-renov8/befly-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kea-renov8/befly-gateway
- Repository: https://github.com/kea-renov8/befly-gateway

## Overview

##### Project Type and Purpose
- This is a reactive API‐Gateway built with Kotlin and Spring Boot (WebFlux).
- Its role is to authenticate, authorize, log, and proxy client requests to downstream microservices via WebClient.

##### Components from the File Tree
a. **Entry Point**
- `BeflyGatewayApplication.kt` – main Spring Boot application.
b. **Configuration**
- `GatewayConfig.kt` – route definitions, path predicates, timeouts.
- `SecurityConfig.kt` – security filter chain, permitted paths.
- `WebClientConfig.kt` – WebClient beans for downstream calls.
c. **Filters & Handlers**
- `JwtAuthenticationFilter.kt` & `RefreshAuthenticationFilter.kt` – JWT validation and token refresh.
- `LoggingFilter.kt` – request/response logging.
- `CustomAuthenticationEntryPoint.kt` – error entry point.
- `OAuth2SuccessHandler.kt` – OAuth2 login success handling.
d. **JWT Utilities**
- `JwtProvider.kt` – issue/validate tokens.
e. **DTOs & Error Codes**
- Data transfer objects for login requests/responses, error responses.
- `ErrorCode.kt` – standardized error codes.
f. **CI/CD & Docker**
- `Dockerfile.dev/prod` – container images for environments.
- GitHub Actions workflows under `.github/workflows` for CI (build & test) and CD (deploy).

##### README Insights
- Confirms stacks: Kotlin, Spring WebFlux API Gateway.

1. **Clients** (blue)
- Mobile/Web Frontend
- External 3rd‐party services
2. **API Gateway** (green)
- HTTP Ingress Layer
- Filter Chain:
- Authentication/Authorization Filters
- Logging Filter
- Error Handler
- Routing Component (GatewayConfig)
- WebClient Pool (WebClientConfig)
- JWT Module (JwtProvider)
3. **Downstream Services** (orange)
- Auth Service
- User Service
- Orders Service (etc.)
- Docker Registry
- CI/CD Pipelines (GitHub Actions)
- Pipeline flow: Developer commit → GitHub Actions CI → Build & Test → Docker push → Deployment.
c. **Architectural Patterns / Principles**
- **Gateway Pattern**: central entry point for microservices.
- **Filter Chain**: modular cross‐cutting concerns (auth, logging, error handling).
- **Reactive Non‐blocking I/O** via Spring WebFlux and WebClient.
- **Externalized Configuration** via `application.yml` (not shown, but implied).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Mobile["Mobile/Web Frontend"]:::clients
        External3rd["External 3rd-party Services"]:::clients
    end

    %% API Gateway Layer
    subgraph "API Gateway" 
        direction TB
        EntryPoint["BeflyGatewayApplication"]:::gateway
        subgraph "Configurations"
            GatewayCfg["GatewayConfig"]:::config
            SecurityCfg["SecurityConfig"]:::config
            WebClientCfg["WebClientConfig"]:::config
        end
        subgraph "Filter Chain"
            JwtFilter["JwtAuthenticationFilter"]:::filter
            RefreshFilter["RefreshAuthenticationFilter"]:::filter
            LoggingFilter["LoggingFilter"]:::filter
        end
        CustomEntry["CustomAuthenticationEntryPoint"]:::filter
        OAuth2Success["OAuth2SuccessHandler"]:::filter
        JwtProvider["JwtProvider"]:::jwt
        PathWhitelist["PathWhitelistUtil"]:::utility
        subgraph "DTOs & Error Codes"
            LoginReq["LoginRequest"]:::dto
            LoginRes["LoginResponse"]:::dto
            AuthRes["AuthResponse"]:::dto
            ErrorRes["ErrorResponse"]:::dto
            ErrorCode["ErrorCode"]:::dto
        end
    end

    %% Downstream Services
    subgraph "Downstream Services"
        direction TB
        AuthService["Auth Service"]:::service
        UserService["User Service"]:::service
        OrdersService["Orders Service"]:::service
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        DockerRegistry["Docker Registry"]:::infra
        subgraph "CI/CD Pipelines"
            DevCI["befly-dev-ci.yml"]:::infra
            ProdCI["befly-prod-ci.yml"]:::infra
            DevCD["befly-dev-cd.yml"]:::infra
        end
        DockerDev["Dockerfile.dev"]:::infra
        DockerProd["Dockerfile.prod"]:::infra
    end

    %% Flows
    Mobile -->|"HTTP/HTTPS, JSON"| EntryPoint
    External3rd -->|"HTTP/HTTPS, JSON"| EntryPoint

    EntryPoint --> GatewayCfg
    EntryPoint --> SecurityCfg
    EntryPoint --> WebClientCfg

    EntryPoint --> JwtFilter
    JwtFilter --> RefreshFilter
    RefreshFilter --> LoggingFilter
    LoggingFilter -->|onError| CustomEntry
    LoggingFilter --> OAuth2Success

    OAuth2Success --> GatewayCfg
    GatewayCfg --> WebClientCfg
    WebClientCfg --> JwtProvider
    JwtProvider --> PathWhitelist

    PathWhitelist --> AuthService
    WebClientCfg --> AuthService
    WebClientCfg --> UserService
    WebClientCfg --> OrdersService

    AuthService -->|Mono/Flux| EntryPoint

    %% CI/CD Flow
    DevCommit["Developer Commit"]:::infra -.-> DevCI
    DevCI -->|"Build & Test"| DockerDev
    DockerDev --> DockerRegistry
    ProdCI -->|"Build & Test"| DockerProd
    DockerProd --> DockerRegistry
    DevCD -->|"Deploy to Dev"| DockerRegistry
    ProdCI -.-> DevCD

    %% Click events
    click EntryPoint "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/BeflyGatewayApplication.kt"
    click GatewayCfg "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/config/GatewayConfig.kt"
    click SecurityCfg "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/config/SecurityConfig.kt"
    click WebClientCfg "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/client/WebClientConfig.kt"
    click JwtFilter "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/filter/JwtAuthenticationFilter.kt"
    click RefreshFilter "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/filter/RefreshAuthenticationFilter.kt"
    click LoggingFilter "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/filter/LoggingFilter.kt"
    click CustomEntry "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/filter/CustomAuthenticationEntryPoint.kt"
    click OAuth2Success "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/handler/OAuth2SuccessHandler.kt"
    click JwtProvider "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/jwt/JwtProvider.kt"
    click ErrorCode "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/code/ErrorCode.kt"
    click LoginReq "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/dto/LoginRequest.kt"
    click LoginRes "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/dto/LoginResponse.kt"
    click AuthRes "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/dto/AuthResponse.kt"
    click ErrorRes "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/dto/ErrorResponse.kt"
    click PathWhitelist "https://github.com/kea-renov8/befly-gateway/blob/develop/src/main/kotlin/befly/beflygateway/utils/PathWhitelistUtil.kt"
    click DevCI "https://github.com/kea-renov8/befly-gateway/blob/develop/.github/workflows/befly-dev-ci.yml"
    click ProdCI "https://github.com/kea-renov8/befly-gateway/blob/develop/.github/workflows/befly-prod-ci.yml"
    click DevCD "https://github.com/kea-renov8/befly-gateway/blob/develop/.github/workflows/befly-dev-cd.yml"
    click DockerDev "https://github.com/kea-renov8/befly-gateway/blob/develop/Dockerfile.dev"
    click DockerProd "https://github.com/kea-renov8/befly-gateway/blob/develop/Dockerfile.prod"

    %% Styles
    classDef clients fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef gateway fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef config fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef filter fill:#FFF3E0,stroke:#FB8C00,color:#FB8C00;
    classDef jwt fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA;
    classDef utility fill:#E1F5FE,stroke:#039BE5,color:#039BE5;
    classDef dto fill:#FBE9E7,stroke:#D84315,color:#D84315;
    classDef service fill:#FFE0B2,stroke:#EF6C00,color:#EF6C00;
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,color:#616161,stroke-dasharray: 5 5;
```
