# acenelio/ms-course architecture

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

- Interactive diagram: https://gitdiagram.com/acenelio/ms-course
- Repository: https://github.com/acenelio/ms-course

## Overview

##### Project type and purpose
- This is a Java/Spring Boot microservices ecosystem built for a course on Spring Cloud & Spring Boot.
- It implements common microservice patterns: service registry (Eureka), centralized configuration (Config Server), API gateway (Zuul), load-balancing (Ribbon), client-side load-balancing/fault tolerance (Feign/Hystrix), OAuth2 authentication, and several domain services (Worker, Payroll, User).

##### File structure
- Top-level modules (each a Maven sub-project):
- hr-config-server
- hr-eureka-server
- hr-api-gateway-zuul
- hr-worker
- hr-payroll
- hr-user
- hr-oauth
- Each service has the typical Spring Boot layout: src/main/java (application class, config, resources, controllers, entities, repositories/Feign clients, services).
- Configuration files:
- bootstrap.properties (for Config Server clients)
- application.properties (service settings, ports, DB, Eureka)
- Build scripts: pom.xml in each module, Maven wrapper.
- Postman environment and collection JSON at the root for manual testing.

##### README insights
- The course phases map directly to the modules:
- Phase 1: simple communication between hr-worker and hr-payroll (Feign, Ribbon)
- Phase 2: Eureka service registry, Hystrix, Zuul gateway
- Phase 3: Config Server for externalized, centralized configuration
- Phase 4: Authentication & authorization with hr-user and hr-oauth (JWT), gateway security.

a. Main components
- Clients (Postman, Browser, Mobile App)
- API Gateway (hr-api-gateway-zuul)
- Authentication Service (hr-oauth)
- User Service (hr-user)
- Worker Service (hr-worker)
- Payroll Service (hr-payroll)
- Service Registry (hr-eureka-server)
- Config Server (hr-config-server)
- Databases (H2 in-memory per service)
b. Relationships & interactions
- At startup, each microservice calls Config Server to fetch its config, then registers with Eureka.
- Clients call the API Gateway.
- Gateway routes requests to downstream services via Eureka discovery.
- Payroll Service calls Worker Service via Feign+Ribbon (through Eureka).
- Gateway secures routes: first authenticates via OAuth2 (hr-oauth), then passes JWT to downstream.
- Hystrix wraps calls (circuit breaker) on RPC paths.
c. Architectural patterns & principles
- Microservices architecture: each service is independent, with its own data store.
- Service Registry & Discovery (Eureka).
- Centralized Configuration (Config Server).
- API Gateway (Zuul) for routing, security, load-balancing at the edge.
- Client-side load-balancing (Ribbon) & declarative HTTP clients (Feign).
- Fault tolerance (Hystrix circuit breaker).
- OAuth2 authorization server issuing JWT tokens.
d. Technologies & frameworks
- Spring Boot 2.3.4, Java 11
- Spring Cloud Netflix: Eureka, Zuul, Ribbon, Feign, Hystrix
- Spring Cloud Config
- Spring Security OAuth2
- H2 in-memory DB

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Clients (Postman, Browser, Mobile)"]:::client

    %% Infrastructure
    subgraph "Infrastructure Services"
        direction TB
        ConfigServer["Config Server"]:::infra
        EurekaServer["Service Registry (Eureka)"]:::infra
        ApiGateway["API Gateway (Zuul)"]:::infra
    end

    %% Domain Services
    subgraph "Domain Microservices"
        direction TB
        OAuthService["OAuth2 Auth Service"]:::domain
        UserService["User Service"]:::domain
        WorkerService["Worker Service"]:::domain
        PayrollService["Payroll Service"]:::domain
    end

    %% Databases
    OAuthDB[(H2 DB)]:::db
    UserDB[(H2 DB)]:::db
    WorkerDB[(H2 DB)]:::db
    PayrollDB[(H2 DB)]:::db

    %% Startup Flow
    ConfigServer -->|"serves config to"| EurekaServer
    OAuthService -->|"fetch config"| ConfigServer
    UserService -->|"fetch config"| ConfigServer
    WorkerService -->|"fetch config"| ConfigServer
    PayrollService -->|"fetch config"| ConfigServer

    OAuthService -->|"register"| EurekaServer
    UserService -->|"register"| EurekaServer
    WorkerService -->|"register"| EurekaServer
    PayrollService -->|"register"| EurekaServer
    ApiGateway -->|"register"| EurekaServer

    %% Client to Gateway
    Clients -->|"HTTP/REST"| ApiGateway

    %% Gateway to Services
    ApiGateway -->|"routes/auth"| OAuthService
    ApiGateway -->|"routes/user"| UserService
    ApiGateway -->|"routes/worker"| WorkerService
    ApiGateway -->|"routes/payroll"| PayrollService

    %% OAuth Flow
    Clients -->|"obtain token"| OAuthService
    OAuthService -->|"issue JWT"| Clients
    ApiGateway -->|"validate token"| OAuthService

    %% Service-to-Service
    PayrollService -->|"Feign/Ribbon"| WorkerService
    PayrollService -.->|"fallback (Hystrix)"| WorkerService

    %% Service Databases
    OAuthService --> OAuthDB
    UserService --> UserDB
    WorkerService --> WorkerDB
    PayrollService --> PayrollDB

    %% Click Events
    click ApiGateway "https://github.com/acenelio/ms-course/tree/main/hr-api-gateway-zuul/src/main/java/com/devsuperior/hrapigatewayzuul"
    click ConfigServer "https://github.com/acenelio/ms-course/tree/main/hr-config-server/src/main/java/com/devsuperior/hrconfigserver"
    click EurekaServer "https://github.com/acenelio/ms-course/tree/main/hr-eureka-server/src/main/java/com/devsuperior/hreurekaserver"
    click OAuthService "https://github.com/acenelio/ms-course/tree/main/hr-oauth/src/main/java/com/devsuperior/hroauth"
    click UserService "https://github.com/acenelio/ms-course/tree/main/hr-user/src/main/java/com/devsuperior/hruser"
    click WorkerService "https://github.com/acenelio/ms-course/tree/main/hr-worker/src/main/java/com/devsuperior/hrworker"
    click PayrollService "https://github.com/acenelio/ms-course/tree/main/hr-payroll/src/main/java/com/devsuperior/hrpayroll"

    %% Styles
    classDef infra fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef domain fill:#A9DFBF,stroke:#196F3D,color:#196F3D;
    classDef db shape: cylinder,fill:#F9E79F,stroke:#B9770E,color:#B9770E;
    classDef client fill:#F5B7B1,stroke:#C0392B,color:#C0392B;
```
