# dmslob/atlas-hotel architecture

> Architecture diagram of the GitHub repository dmslob/atlas-hotel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmslob/atlas-hotel
- Repository: https://github.com/dmslob/atlas-hotel

## Overview

1. **System shape**
   This repository is a Spring-based microservice suite for a hotel domain. It is split into a **control plane** for configuration/discovery/routing and a **business plane** for guest, room, and reservation operations.

2. **Control plane services**
   - **config-server** centralizes runtime configuration. Its `src/main/resources/config/*.yaml` files hold per-service config for guest, room, and reservation services.
   - **eurekaserver** is the service registry used for discovery.
   - **gatewayserver** is the edge entry point for client traffic and contains request tracing and fallback handling.

3. **Request entry path**
   External clients are expected to hit the **gateway** first. The gateway applies request filtering/tracing, then routes to backend services using registry-based discovery. The presence of a `FallbackController` indicates it is also the failure boundary when downstream calls fail.

4. **Business services**
   - **guest-service** manages guest data.
   - **room-service** manages room data.
   - **reservation-service** manages reservations and coordinates with the other two services.
   
   Each service follows the same layered pattern: `controller -> service -> repository -> entity`, with DTOs/models for API contracts and a global exception handler for consistent error responses.

5. **Reservation orchestration**
   `reservation-service` is the only service that clearly depends on other services at runtime. It uses **Feign clients** for `guest-service` and `room-service`, plus fallback classes for resilience. That makes reservation the orchestration point for combining guest and room information with reservation persistence.

6. **Data ownership**
   Each domain service has its own `schema.sql` and `data.sql`, which strongly suggests **service-local persistence** rather than a shared database. The repositories are isolated per service, reinforcing bounded contexts:
   - `GuestRepository`
   - `RoomRepository`
   - `ReservationRepository`

7. **Configuration and runtime binding**
   Services are designed to bootstrap from the config server and register themselves in Eureka. The config server exposes service-specific YAML by application name, so runtime behavior is externalized from the codebase and can be refreshed without redeploying.

8. **Resilience and failure behavior**
   The architecture includes explicit resilience points:
   - Feign fallback implementations in reservation-service
   - Gateway fallback controller
   - Actuator-based refresh endpoints
   - Readme references to Spring Cloud Bus refresh via RabbitMQ
   
   This indicates the system is meant to tolerate partial downstream failures and support live config changes.

9. **Observability stack**
   The `docker-compose/observability` folder includes **Prometheus, Grafana, Loki, Tempo, and Alloy**. That means the services expose metrics/logs/traces via Spring Boot Actuator, Prometheus scrapes metrics, and Grafana is the visualization layer. Observability is a first-class part of the runtime topology, not an afterthought.

10. **Deployment model**
    The repo is organized for **containerized local composition** and image publishing. The README shows:
    - Jib-based image builds per service
    - Docker Hub image pushes
    - `docker-compose/default` for bringing the stack up locally
   
    So the main deployment unit is the individual microservice container, coordinated by compose in local environments.

11. **API surface and developer access**
    The domain services expose Swagger UI endpoints for interactive API docs, which implies they are independently consumable APIs rather than internal-only components. The gateway and control-plane services are operational infrastructure rather than user-facing business APIs.

12. **Optional external integration**
    The README mentions **Keycloak** for authN/authZ, but it is not represented as an in-repo service. Treat it as an external optional identity provider that can sit in front of the gateway or protected services.

Main entry points: [`gatewayserver/src/main/java/com/dmslob/gatewayserver/GatewayServerApplication.java`](https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/GatewayServerApplication.java) (Gateway), [`guest-service/src/main/java/com/dmslob/guestservice/GuestServiceApplication.java`](https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/GuestServiceApplication.java) (Guest Service), [`room-service/src/main/java/com/dmslob/roomservice/RoomServiceApplication.java`](https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/RoomServiceApplication.java) (Room Service), [`docker-compose/default/docker-compose.yml`](https://github.com/dmslob/atlas-hotel/blob/main/docker-compose/default/docker-compose.yml) (Compose Stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_config_server["Config Server<br/>Spring config service"]
  node_config_files["Service Config<br/>YAML config set"]
  node_eureka_server["Eureka Server<br/>Service registry"]
  node_gateway_server["Gateway"]
  node_request_trace{{"Trace Filter<br/>Gateway filter"}}
  node_fallback_controller["Fallback API<br/>Gateway fallback"]
end

subgraph group_business["Business Plane"]
  node_guest_app["Guest Service<br/>Domain service"]
  node_guest_controller["Guest API<br/>Web controller"]
  node_guest_service_impl["Guest Logic<br/>Service layer"]
  node_guest_repo[("Guest Repo<br/>Persistence")]
  node_room_app["Room Service<br/>Domain service"]
  node_room_controller["Room API<br/>Web controller"]
  node_room_service_impl["Room Logic<br/>Service layer"]
  node_room_repo[("Room Repo<br/>Persistence")]
  node_reservation_app["Reservation Service<br/>Domain service"]
  node_reservation_controller["Reservation API<br/>Web controller"]
  node_reservation_service_impl["Reservation Logic<br/>Orchestrator"]
  node_reservation_clients{{"Feign Clients<br/>Remote clients"}}
  node_reservation_repo[("Reservation Repo<br/>Persistence")]
  node_guest_fallback{{"Guest Fallback<br/>Feign fallback<br/>[GuestFallback.java]"}}
  node_room_fallback{{"Room Fallback<br/>Feign fallback<br/>[RoomFallback.java]"}}
end

subgraph group_ops["Operations"]
  node_compose_stack["Compose Stack<br/>Deployment<br/>[docker-compose.yml]"]
  node_observability_stack["Observability<br/>Telemetry stack<br/>[prometheus.yml]"]
end

subgraph group_external["External"]
  node_keycloak(("Keycloak<br/>External IdP"))
end

node_config_server -->|"serves"| node_config_files
node_config_server -.->|"configures"| node_guest_app
node_config_server -.->|"configures"| node_room_app
node_config_server -.->|"configures"| node_reservation_app
node_eureka_server -->|"registers"| node_gateway_server
node_eureka_server -->|"registers"| node_guest_app
node_eureka_server -->|"registers"| node_room_app
node_eureka_server -->|"registers"| node_reservation_app
node_gateway_server -->|"applies"| node_request_trace
node_gateway_server -->|"falls back"| node_fallback_controller
node_gateway_server -.->|"routes via"| node_eureka_server
node_gateway_server -.->|"routes to"| node_guest_app
node_gateway_server -.->|"routes to"| node_room_app
node_gateway_server -.->|"routes to"| node_reservation_app
node_guest_app -->|"exposes"| node_guest_controller
node_guest_controller -->|"delegates"| node_guest_service_impl
node_guest_service_impl -->|"persists via"| node_guest_repo
node_room_app -->|"exposes"| node_room_controller
node_room_controller -->|"delegates"| node_room_service_impl
node_room_service_impl -->|"persists via"| node_room_repo
node_reservation_app -->|"exposes"| node_reservation_controller
node_reservation_controller -->|"delegates"| node_reservation_service_impl
node_reservation_service_impl -->|"persists via"| node_reservation_repo
node_reservation_service_impl -->|"calls"| node_reservation_clients
node_reservation_clients -.->|"fetches guest"| node_guest_app
node_reservation_clients -.->|"fetches room"| node_room_app
node_reservation_clients -->|"fallback"| node_guest_fallback
node_reservation_clients -->|"fallback"| node_room_fallback
node_compose_stack -.->|"starts"| node_config_server
node_compose_stack -.->|"starts"| node_eureka_server
node_compose_stack -.->|"starts"| node_gateway_server
node_compose_stack -.->|"starts"| node_guest_app
node_compose_stack -.->|"starts"| node_room_app
node_compose_stack -.->|"starts"| node_reservation_app
node_observability_stack -.->|"scrapes"| node_guest_app
node_observability_stack -.->|"scrapes"| node_room_app
node_observability_stack -.->|"scrapes"| node_reservation_app
node_keycloak -.->|"secures"| node_gateway_server

click node_config_server "https://github.com/dmslob/atlas-hotel/blob/main/config-server/src/main/java/com/dmslob/configserver/ConfigServerApplication.java"
click node_config_files "https://github.com/dmslob/atlas-hotel/tree/main/config-server/src/main/resources/config"
click node_eureka_server "https://github.com/dmslob/atlas-hotel/blob/main/eurekaserver/src/main/java/com/dmslob/eurekaserver/EurekaServerApplication.java"
click node_gateway_server "https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/GatewayServerApplication.java"
click node_request_trace "https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/filters/RequestTraceFilter.java"
click node_fallback_controller "https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/controller/FallbackController.java"
click node_guest_app "https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/GuestServiceApplication.java"
click node_guest_controller "https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/controller/GuestController.java"
click node_guest_service_impl "https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/service/GuestServiceImpl.java"
click node_guest_repo "https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/repository/GuestRepository.java"
click node_room_app "https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/RoomServiceApplication.java"
click node_room_controller "https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/controller/RoomController.java"
click node_room_service_impl "https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/service/RoomServiceImpl.java"
click node_room_repo "https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/repository/RoomRepository.java"
click node_reservation_app "https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/ReservationServiceApplication.java"
click node_reservation_controller "https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/controller/ReservationController.java"
click node_reservation_service_impl "https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/ReservationServiceImpl.java"
click node_reservation_clients "https://github.com/dmslob/atlas-hotel/tree/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/client"
click node_reservation_repo "https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/repository/ReservationRepository.java"
click node_guest_fallback "https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/client/GuestFallback.java"
click node_room_fallback "https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/client/RoomFallback.java"
click node_compose_stack "https://github.com/dmslob/atlas-hotel/blob/main/docker-compose/default/docker-compose.yml"
click node_observability_stack "https://github.com/dmslob/atlas-hotel/blob/main/docker-compose/observability/prometheus/prometheus.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config_server,node_config_files,node_eureka_server,node_gateway_server,node_request_trace,node_fallback_controller toneBlue
class node_guest_app,node_guest_controller,node_guest_service_impl,node_guest_repo,node_room_app,node_room_controller,node_room_service_impl,node_room_repo,node_reservation_app,node_reservation_controller,node_reservation_service_impl,node_reservation_clients,node_reservation_repo,node_guest_fallback,node_room_fallback toneAmber
class node_compose_stack,node_observability_stack toneMint
class node_keycloak toneRose
```

## Components

### Control Plane

Discovery, config, and edge routing

- [Config Server](https://github.com/dmslob/atlas-hotel/blob/main/config-server/src/main/java/com/dmslob/configserver/ConfigServerApplication.java): Spring config service · Centralized runtime configuration service · `config-server/src/main/java/com/dmslob/configserver/ConfigServerApplication.java`
- [Service Config](https://github.com/dmslob/atlas-hotel/tree/main/config-server/src/main/resources/config): YAML config set · Per-service configuration loaded by the config server · `config-server/src/main/resources/config`
- [Eureka Server](https://github.com/dmslob/atlas-hotel/blob/main/eurekaserver/src/main/java/com/dmslob/eurekaserver/EurekaServerApplication.java): Service registry · Discovery registry for backend services · `eurekaserver/src/main/java/com/dmslob/eurekaserver/EurekaServerApplication.java`
- [Gateway](https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/GatewayServerApplication.java): API gateway · Edge entry point for client traffic and downstream routing · `gatewayserver/src/main/java/com/dmslob/gatewayserver/GatewayServerApplication.java`
- [Trace Filter](https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/filters/RequestTraceFilter.java): Gateway filter · Adds request tracing and filtering at the edge · `gatewayserver/src/main/java/com/dmslob/gatewayserver/filters/RequestTraceFilter.java`
- [Fallback API](https://github.com/dmslob/atlas-hotel/blob/main/gatewayserver/src/main/java/com/dmslob/gatewayserver/controller/FallbackController.java): Gateway fallback · Failure boundary returned when routed calls fail · `gatewayserver/src/main/java/com/dmslob/gatewayserver/controller/FallbackController.java`

### Business Plane

Domain services for guests, rooms, and reservations

- [Guest Service](https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/GuestServiceApplication.java): Domain service · Manages guest data and APIs · `guest-service/src/main/java/com/dmslob/guestservice/GuestServiceApplication.java`
- [Guest API](https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/controller/GuestController.java): Web controller · Guest HTTP entrypoint · `guest-service/src/main/java/com/dmslob/guestservice/controller/GuestController.java`
- [Guest Logic](https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/service/GuestServiceImpl.java): Service layer · Guest domain operations and validation · `guest-service/src/main/java/com/dmslob/guestservice/service/GuestServiceImpl.java`
- [Guest Repo](https://github.com/dmslob/atlas-hotel/blob/main/guest-service/src/main/java/com/dmslob/guestservice/repository/GuestRepository.java): Persistence · Guest data access boundary · `guest-service/src/main/java/com/dmslob/guestservice/repository/GuestRepository.java`
- [Room Service](https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/RoomServiceApplication.java): Domain service · Manages room data and APIs · `room-service/src/main/java/com/dmslob/roomservice/RoomServiceApplication.java`
- [Room API](https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/controller/RoomController.java): Web controller · Room HTTP entrypoint · `room-service/src/main/java/com/dmslob/roomservice/controller/RoomController.java`
- [Room Logic](https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/service/RoomServiceImpl.java): Service layer · Room domain operations and validation · `room-service/src/main/java/com/dmslob/roomservice/service/RoomServiceImpl.java`
- [Room Repo](https://github.com/dmslob/atlas-hotel/blob/main/room-service/src/main/java/com/dmslob/roomservice/repository/RoomRepository.java): Persistence · Room data access boundary · `room-service/src/main/java/com/dmslob/roomservice/repository/RoomRepository.java`
- [Reservation Service](https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/ReservationServiceApplication.java): Domain service · Coordinates reservations across guest and room domains · `reservation-service/src/main/java/com/dmslob/reservationservice/ReservationServiceApplication.java`
- [Reservation API](https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/controller/ReservationController.java): Web controller · Reservation HTTP entrypoint · `reservation-service/src/main/java/com/dmslob/reservationservice/controller/ReservationController.java`
- [Reservation Logic](https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/ReservationServiceImpl.java): Orchestrator · Combines local persistence with remote guest and room lookups · `reservation-service/src/main/java/com/dmslob/reservationservice/service/ReservationServiceImpl.java`
- [Feign Clients](https://github.com/dmslob/atlas-hotel/tree/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/client): Remote clients · Typed clients for guest-service and room-service · `reservation-service/src/main/java/com/dmslob/reservationservice/service/client`
- [Reservation Repo](https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/repository/ReservationRepository.java): Persistence · Reservation data access boundary · `reservation-service/src/main/java/com/dmslob/reservationservice/repository/ReservationRepository.java`
- [Guest Fallback](https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/client/GuestFallback.java): Feign fallback · Resilience path when guest lookup fails · `reservation-service/src/main/java/com/dmslob/reservationservice/service/client/GuestFallback.java`
- [Room Fallback](https://github.com/dmslob/atlas-hotel/blob/main/reservation-service/src/main/java/com/dmslob/reservationservice/service/client/RoomFallback.java): Feign fallback · Resilience path when room lookup fails · `reservation-service/src/main/java/com/dmslob/reservationservice/service/client/RoomFallback.java`

### Operations

Local composition and observability

- [Compose Stack](https://github.com/dmslob/atlas-hotel/blob/main/docker-compose/default/docker-compose.yml): Deployment · Local container composition for the whole system · `docker-compose/default/docker-compose.yml`
- [Observability](https://github.com/dmslob/atlas-hotel/blob/main/docker-compose/observability/prometheus/prometheus.yml): Telemetry stack · Prometheus, Grafana, Loki, Tempo, and Alloy · `docker-compose/observability/prometheus/prometheus.yml`

### External

Outside systems referenced by the repo

- **Keycloak**: External IdP · Optional external identity provider referenced by the repository

## Connections

- Config Server → Service Config: serves · Publishes service-specific runtime configuration
- Config Server → Guest Service: configures · Provides guest-service settings at bootstrap
- Config Server → Room Service: configures · Provides room-service settings at bootstrap
- Config Server → Reservation Service: configures · Provides reservation-service settings at bootstrap
- Eureka Server → Gateway: registers · Gateway discovers downstream services through the registry
- Eureka Server → Guest Service: registers · Guest service advertises itself for discovery
- Eureka Server → Room Service: registers · Room service advertises itself for discovery
- Eureka Server → Reservation Service: registers · Reservation service advertises itself for discovery
- Gateway → Trace Filter: applies · Edge filter chain adds request tracing
- Gateway → Fallback API: falls back · Handles downstream failures at the gateway boundary
- Gateway → Eureka Server: routes via · Resolves backend destinations through service discovery
- Gateway → Guest Service: routes to · Forwards guest traffic to the guest service
- Gateway → Room Service: routes to · Forwards room traffic to the room service
- Gateway → Reservation Service: routes to · Forwards reservation traffic to the reservation service
- Guest Service → Guest API: exposes · HTTP API surface for guest operations
- Guest API → Guest Logic: delegates · Controller delegates business logic to the service layer
- Guest Logic → Guest Repo: persists via · Guest logic stores and reads guest records
- Room Service → Room API: exposes · HTTP API surface for room operations
- Room API → Room Logic: delegates · Controller delegates business logic to the service layer
- Room Logic → Room Repo: persists via · Room logic stores and reads room records
- Reservation Service → Reservation API: exposes · HTTP API surface for reservation operations
- Reservation API → Reservation Logic: delegates · Controller delegates orchestration to the service layer
- Reservation Logic → Reservation Repo: persists via · Reservation state is stored locally
- Reservation Logic → Feign Clients: calls · Uses remote clients for guest and room lookups
- Feign Clients → Guest Service: fetches guest · Remote guest lookup through service discovery
- Feign Clients → Room Service: fetches room · Remote room lookup through service discovery
- Feign Clients → Guest Fallback: fallback · Guest client has a resilience fallback
- Feign Clients → Room Fallback: fallback · Room client has a resilience fallback
- Compose Stack → Config Server: starts · Compose brings up the configuration service
- Compose Stack → Eureka Server: starts · Compose brings up the registry
- Compose Stack → Gateway: starts · Compose brings up the edge gateway
- Compose Stack → Guest Service: starts · Compose brings up guest-service
- Compose Stack → Room Service: starts · Compose brings up room-service
- Compose Stack → Reservation Service: starts · Compose brings up reservation-service
- Observability → Guest Service: scrapes · Observability stack collects service telemetry
- Observability → Room Service: scrapes · Observability stack collects service telemetry
- Observability → Reservation Service: scrapes · Observability stack collects service telemetry
- Keycloak → Gateway: secures · Optional external identity provider in front of the gateway