# oatpp/example-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/oatpp/example-microservices
- Repository: https://github.com/oatpp/example-microservices

## Overview

##### Project Type & Purpose
- This is a microservices architecture example built with Oat++. The key objective is to run individual microservices (book-service, user-service) either as standalone apps listening on specific ports (8001 and 8002 respectively) or as a combined monolithic executable.
- The facade service on port 8000 acts as an orchestrator – merging book and user data to respond to client requests.

##### Main Components
a. Client/External Consumers: Represent the clients that consume the unified API (e.g., via curl).
b. Facade Service:
- Acts as the API gateway.
- Contains controllers (BookController, UserController) and service logic to merge data from backend services.
- Runs on port 8000.
c. Book-Service:
- Contains its own controller (BookController) and database logic (see the db sub-folder and BookDto).
- Runs on port 8002.
d. User-Service:
- Contains its own controller (UserController) and database logic (see its db folder and UserDto).
- Runs on port 8001.
e. Optional: Monolith Build
- A combined monolith build (monolith/all-services) showing that all microservices can be compiled together.

##### Architectural Relationships & Interaction
- Incoming API calls arriving at the facade.
- Facade service making HTTP/REST calls or internal calls to book-service and user-service to retrieve respective data.
- Data flow back from both services to the facade, and then finally to the client.
- You may also include deployment/dependency relationships (for example, communication via network ports).
- That Docker is used for containerization (each service has its own Dockerfile) and that CMake is used for building the project.

##### Technical Stack & Architectural Patterns
- That the services use the Oat++ framework for REST APIs with Swagger integration (SwaggerComponent).
- That the pattern includes a layered structure (controllers, DTOs, database abstraction) which may be depicted with multiple small layers inside each service component.
- Possibility for monolithization – you could have an inset or alternate view showing the consolidated monolith layering all services together.

- Each component should have a clear label.

[Client]
│
▼
[Facade Service (8000)]
│          │
▼          ▼
[User Service (8001)]   [Book Service (8002)]

Along with detailed annotations for internal components (controllers, DTOs, database modules) within each service. This approach captures both the microservices pattern and the unique aggregation done by the facade.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client
    Client["Client/External Consumer"]:::client
    Client -->|"API_call"| Facade

    %% Facade Service (Port 8000)
    subgraph "Facade Service (Port 8000)"
        Facade["Facade Service (Port 8000)"]:::service
        FacadeControllers["Controllers"]:::internal
        Facade_BookController["BookController"]:::internal
        Facade_UserController["UserController"]:::internal
        FacadeServiceLogic["Data Aggregation Service"]:::internal
    end

    Facade -->|"uses"| FacadeControllers
    FacadeControllers -->|"includes"| Facade_BookController
    FacadeControllers -->|"includes"| Facade_UserController
    Facade -->|"delegates_to"| FacadeServiceLogic

    %% Book Service (Port 8002)
    subgraph "Book Service (Port 8002)"
        BookService["Book Service (Port 8002)"]:::service
        BookControllers["Controllers"]:::internal
        BookController["BookController"]:::internal
        BookDB["Database (Book DB)"]:::db
        BookDTO["Book DTO"]:::internal
    end

    BookService -->|"initializes"| BookControllers
    BookControllers -->|"contains"| BookController
    BookService -->|"manages"| BookDB
    BookDB -->|"maps_to"| BookDTO

    %% User Service (Port 8001)
    subgraph "User Service (Port 8001)"
        UserService["User Service (Port 8001)"]:::service
        UserControllers["Controllers"]:::internal
        UserController["UserController"]:::internal
        UserDB["Database (User DB)"]:::db
        UserDTO["User DTO"]:::internal
    end

    UserService -->|"initializes"| UserControllers
    UserControllers -->|"contains"| UserController
    UserService -->|"manages"| UserDB
    UserDB -->|"maps_to"| UserDTO

    %% Inter-Service Communication: Facade fetching data from Book and User Services
    FacadeServiceLogic -->|"fetches_from"| BookService
    FacadeServiceLogic -->|"fetches_from"| UserService

    %% Response Flow: Facade responds back to Client
    Facade -->|"responds_to"| Client

    %% Monolith Build (Combined Services)
    Monolith["Monolith Build (All Services)"]:::service
    Monolith -->|"combines"| Facade
    Monolith -->|"combines"| BookService
    Monolith -->|"combines"| UserService

    %% Build & Deployment Tools
    subgraph "Build & Deployment Tools"
        DockerFacade["Dockerfile (Facade)"]:::tool
        DockerBook["Dockerfile (Book-Service)"]:::tool
        DockerUser["Dockerfile (User-Service)"]:::tool
        BuildScripts["Global Build Scripts"]:::tool
        CICD["CI/CD: azure-pipelines.yml"]:::tool
    end

    %% Association of Tools with Services
    DockerFacade --- Facade
    DockerBook --- BookService
    DockerUser --- UserService
    BuildScripts --- Monolith
    CICD --- Monolith

    %% Click Events for Facade Service components
    click Facade "https://github.com/oatpp/example-microservices/tree/master/facade/src/facade"
    click Facade_BookController "https://github.com/oatpp/example-microservices/tree/master/facade/src/facade/controller"
    click Facade_UserController "https://github.com/oatpp/example-microservices/tree/master/facade/src/facade/controller"
    click FacadeServiceLogic "https://github.com/oatpp/example-microservices/tree/master/facade/src/facade/service"

    %% Click Events for Book-Service components
    click BookService "https://github.com/oatpp/example-microservices/tree/master/book-service/src/book-service"
    click BookController "https://github.com/oatpp/example-microservices/tree/master/book-service/src/book-service/controller"
    click BookDB "https://github.com/oatpp/example-microservices/tree/master/book-service/src/book-service/db"

    %% Click Events for User-Service components
    click UserService "https://github.com/oatpp/example-microservices/tree/master/user-service/src/user-service"
    click UserController "https://github.com/oatpp/example-microservices/tree/master/user-service/src/user-service/controller"
    click UserDB "https://github.com/oatpp/example-microservices/tree/master/user-service/src/user-service/db"

    %% Click Event for Monolith Build
    click Monolith "https://github.com/oatpp/example-microservices/tree/master/monolith/all-services/"

    %% Click Events for Build & Deployment Tools
    click DockerFacade "https://github.com/oatpp/example-microservices/tree/master/facade/Dockerfile"
    click DockerBook "https://github.com/oatpp/example-microservices/tree/master/book-service/Dockerfile"
    click DockerUser "https://github.com/oatpp/example-microservices/tree/master/user-service/Dockerfile"
    click BuildScripts "https://github.com/oatpp/example-microservices/tree/master/monolith/all-services/"
    click CICD "https://github.com/oatpp/example-microservices/blob/master/azure-pipelines.yml"

%% Style Definitions
classDef client fill:#fceabb,stroke:#d18b00,stroke-width:2px;
classDef service fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
classDef internal fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
classDef db fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px;
classDef tool fill:#ffe082,stroke:#f57f17,stroke-width:2px;
```
