# moyu-x/whitebird architecture

> Architecture diagram of the GitHub repository moyu-x/whitebird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moyu-x/whitebird
- Repository: https://github.com/moyu-x/whitebird

## Overview

##### Main Components
- Microservices:
– whitebird-auth-service (handles authentication & OAuth2 configurations; see its multiple config classes, controllers, and OAuth2 setups)
– whitebird-account-service (deals with user accounts, user roles, and permissions with its controllers, entities, repository and service layers)
– whitebird-config-service (serves as a distributed configuration provider for all services; note its dedicated “config” folder and YAML files)
– whitebird-demo-service (a demo or sandbox service to try out functionality)
– whitebird-gateway-service (acts as an API gateway that provides routing, filtering, rate limiting, and logging)
– whitebird-spring-boot-admin-service (provides operational monitoring and administration, indicated by its distinct port)
– whitebird-elasticsearch-demo (a demo module for Elasticsearch features)
- Common Libraries (whitebird-commons):
– These include various Spring Boot starters such as:
▪ whitebird-core-spring-boot-starter
▪ whitebird-jpa-spring-boot-starter
▪ whitebird-oauth2-spring-boot-starter
▪ whitebird-redis-spring-boot-starer
▪ whitebird-swagger-spring-boot-starter
▪ whitebird-web-spring-boot-starter and even a webflux starter
– These shared modules suggest code reuse and cross-cutting concerns (e.g., security, persistence, caching, and API documentation) across services
- Configuration Repository:
– The whitebird-config-folder contains per-service configuration YAML files that the config service will read and serve during runtime.
- Deployment & Infrastructure:
– The whitebird-deploy-file directory contains docker-compose and Prometheus configuration files that hint at container orchestration and monitoring.

##### Out Relationships and Interactions
- The Gateway then routes requests to the appropriate microservices such as account, auth, or demo services.
- The auth-service (using OAuth2) is central for token handling and client credentials. It might provide tokens that gateway and other services validate.
- The account-service, with its REST controllers and data access layers, handles user management. It likely communicates with a relational database (implied by Flyway migrations in the “db/migration” directories) and uses JPA configurations provided by the common “jpa-spring-boot-starter.”
- The config-service plays a supporting role, providing centralized configuration settings (distributed configuration pattern) to other services.
- The spring-boot-admin-service provides monitoring and health checks across the microservices and might have a bidirectional communication with each service for status updates.
- The Elasticsearch demo service demonstrates integration with external search capabilities and could be depicted interacting with an external Elasticsearch cluster.

##### Architectural Patterns and Technologies
- The overall architecture is based on microservices — each service is developed, deployed, and scaled independently.
- Notice the use of Spring Boot and related modules for web (MVC/REST), security (OAuth2), data persistence (JPA), caching (Redis), API documentation (Swagger), and even reactive programming (via webflux).
- The project uses Gradle as the build tool; Docker (via Jib and docker-compose) for containerization; external monitoring (Prometheus) for observability.
- Service-to-service communication is implicit between the gateway, auth, and other downstream services. Any API clients (e.g., WhitebirdUserClient in auth-service) can be denoted, illustrating inter-service REST or Feign calls.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Nodes
    A("Client"):::external
    DB("Database"):::external
    ES("Elasticsearch Cluster"):::external
    CR("Config Repository"):::config
    DEP("Deployment & Infra"):::deployment
    PROM("Prometheus/Monitoring"):::monitor

    %% Microservices Subgraph
    subgraph "Microservices"
        G("Gateway Service"):::service
        AU("Auth Service"):::service
        AC("Account Service"):::service
        C("Config Service"):::service
        D("Demo Service"):::service
        AD("Admin Service"):::service
        E("Elasticsearch Demo Service"):::service
    end

    %% Shared Libraries Subgraph
    subgraph "Shared Libraries"
        Commons("Whitebird Commons"):::commons
    end

    %% Client to Gateway
    A -->|"requests"| G

    %% Gateway routing to Microservices
    G -->|"routes_to"| AU
    G -->|"routes_to"| AC
    G -->|"routes_to"| D
    G -->|"routes_to"| AD
    G -->|"routes_to"| E

    %% Database connections for Auth and Account
    AU -->|"uses_db"| DB
    AC -->|"JPA/SQL_Migration"| DB

    %% Configuration Repository and Config Service
    CR -->|"YAML_Configs"| C
    C -->|"config_update"| G
    C -->|"config_update"| AU
    C -->|"config_update"| AC
    C -->|"config_update"| D
    C -->|"config_update"| AD
    C -->|"config_update"| E

    %% Elasticsearch Demo interaction
    E -->|"search_queries"| ES

    %% Shared Libraries usage (dashed lines)
    G -.->|"uses"| Commons
    AU -.->|"uses"| Commons
    AC -.->|"uses"| Commons
    C -.->|"uses"| Commons
    D -.->|"uses"| Commons
    AD -.->|"uses"| Commons
    E -.->|"uses"| Commons

    %% Monitoring connections (dashed lines)
    PROM ---|"health_checks"| G
    PROM ---|"health_checks"| AU
    PROM ---|"health_checks"| AC
    PROM ---|"health_checks"| C
    PROM ---|"health_checks"| D
    PROM ---|"health_checks"| AD
    PROM ---|"health_checks"| E

    %% Deployment connections (dashed lines)
    G -.->|"deployed_via"| DEP
    AU -.->|"deployed_via"| DEP
    AC -.->|"deployed_via"| DEP
    C -.->|"deployed_via"| DEP
    D -.->|"deployed_via"| DEP
    AD -.->|"deployed_via"| DEP
    E -.->|"deployed_via"| DEP

    %% Deployment to Monitoring
    DEP --> PROM

    %% Click Events
    click AU "https://github.com/moyu-x/whitebird/tree/master/whitebird-auth-service/"
    click AC "https://github.com/moyu-x/whitebird/tree/master/whitebird-account-service/"
    click C "https://github.com/moyu-x/whitebird/tree/master/whitebird-config-service/"
    click D "https://github.com/moyu-x/whitebird/tree/master/whitebird-demo-service/"
    click G "https://github.com/moyu-x/whitebird/tree/master/whitebird-gateway-service/"
    click E "https://github.com/moyu-x/whitebird/tree/master/whitebird-elasticsearch-demo/"
    click Commons "https://github.com/moyu-x/whitebird/tree/master/whitebird-commons/"
    click CR "https://github.com/moyu-x/whitebird/tree/master/whitebird-config-folder/"
    click DEP "https://github.com/moyu-x/whitebird/tree/master/whitebird-deploy-file/"

    %% Class Styles
    classDef service fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef commons fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#fd7e14,stroke:#e07b39,stroke-width:2px;
    classDef deployment fill:#f8d7da,stroke:#c82333,stroke-width:2px;
    classDef monitor fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
