# spring-petclinic/spring-petclinic-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/spring-petclinic/spring-petclinic-microservices
- Repository: https://github.com/spring-petclinic/spring-petclinic-microservices

## Overview

##### Main components
- API Gateway – This module (spring-petclinic-api-gateway) is responsible for routing external requests to internal services. It is built using Spring Cloud Gateway and handles fallback/circuit breaker logic.
- Service Registry / Discovery Server – This is the Eureka-based discovery server (spring-petclinic-discovery-server) where all microservices register.
- Config Server – (spring-petclinic-config-server) acts as the centralized management for configuration across all services.
- Microservices – There are several key domain services:
- Customers Service (spring-petclinic-customers-service)
- Vets Service (spring-petclinic-vets-service)
- Visits Service (spring-petclinic-visits-service)
- GenAI Service (spring-petclinic-genai-service) which integrates the AI Chatbot functionality.
- There is also an Admin Server (spring-petclinic-admin-server) for management and monitoring.
- Monitoring and Observability Tools – These include:
- Prometheus (docker/prometheus) for metrics.
- Grafana (docker/grafana) for dashboards.
- Tracing components (Zipkin mentioned in the README) for distributed tracing.
- Supporting Infrastructure:
- Docker configurations (docker-compose.yml, Dockerfiles) for container orchestration.
- Chaos Monkey integration (scripts/chaos) – illustrating resilience testing and fault injection.
- Database layer: with configurations for either in-memory HSQLDB or MySQL, as seen by the SQL scripts inside each service’s resources.
- External LLM providers (OpenAI or Azure OpenAI) that are interfaced via the GenAI Service.

##### Relationships and interactions
- The API Gateway sits at the edge and routes incoming requests to the relevant backend microservices.
- All microservices register themselves with the Discovery Server (Eureka) and obtain configuration from the Config Server.
- The Admin Server monitors the microservices, while Prometheus collects application metrics (via Micrometer) that Grafana then visualizes.
- The GenAI Service communicates with external LLM providers and may also receive calls via the API Gateway.
- The chaos scripts and watchers provide fault injection mechanisms that may trigger or simulate failures across the microservices.

##### Architectural patterns and design principles
- Microservices Architecture: Services are segregated by their responsibility (customers, vets, visits, GenAI, etc.) and communicate over REST APIs.
- Centralized Configuration and Service Discovery: Implementation of Spring Cloud Config Server and Eureka for dynamic service registration, making the system resilient and easily scaleable.
- Observability and Resilience: Incorporates monitoring (Prometheus/Grafana), tracers (Zipkin), and circuit breakers (Resilience4j) to handle failures gracefully.
- Containerization and orchestration: Docker compose and Dockerfiles illustrate that the system is packaged as container images to ease local and remote deployments.
- Chaos Engineering: With included Chaos Monkey configuration scripts (in the scripts/chaos folder) to simulate fault conditions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Edge Layer
    subgraph "Client/Edge Layer"
        Client["External Client"]:::client
        APIGateway["API Gateway (Spring Cloud Gateway)"]:::client
    end

    %% Service Layer
    subgraph "Service Layer"
        Cust["Customers Service (Spring Boot)"]:::service
        Vets["Vets Service (Spring Boot)"]:::service
        Visits["Visits Service (Spring Boot)"]:::service
        GenAI["GenAI Service (AI Chatbot Integration)"]:::service
        Admin["Admin Server (Management & Monitoring)"]:::service
    end

    %% Infrastructure & Supporting Services
    subgraph "Infrastructure & Supporting Services"
        Discovery["Discovery Server (Eureka)"]:::infra
        Config["Config Server (Spring Cloud Config)"]:::infra
        Prom["Prometheus (Metrics)"]:::infra
        Graf["Grafana (Dashboards)"]:::infra
        Tracing["Tracing (Zipkin)"]:::infra
        Chaos["Chaos Monkey"]:::infra
        Docker["Docker Configurations"]:::infra
    end

    %% External Integrations
    subgraph "External Integrations"
        LLM["External LLM Providers"]:::external
    end

    %% Connections - Client to API Gateway
    Client -->|"request"| APIGateway

    %% API Gateway routes to Service Layer
    APIGateway -->|"routes"| Cust
    APIGateway -->|"routes"| Vets
    APIGateway -->|"routes"| Visits
    APIGateway -->|"routes"| GenAI
    APIGateway -->|"routes"| Admin

    %% Each microservice registers and fetches configuration
    Cust -->|"registers"| Discovery
    Cust -->|"fetchesConfig"| Config

    Vets -->|"registers"| Discovery
    Vets -->|"fetchesConfig"| Config

    Visits -->|"registers"| Discovery
    Visits -->|"fetchesConfig"| Config

    GenAI -->|"registers"| Discovery
    GenAI -->|"fetchesConfig"| Config

    Admin -->|"registers"| Discovery
    Admin -->|"fetchesConfig"| Config

    %% Monitoring and Tracing connections from Admin server
    Admin -->|"monitors"| Prom
    Admin -->|"monitors"| Graf
    Admin -->|"monitors"| Tracing

    %% GenAI Service integrates with external LLM providers
    GenAI -->|"calls"| LLM

    %% Chaos Monkey applies fault injection on services (dashed lines)
    Chaos ---|"targets"| Cust
    Chaos ---|"targets"| Vets
    Chaos ---|"targets"| Visits
    Chaos ---|"targets"| GenAI
    Chaos ---|"targets"| Admin

    %% Docker Configurations manage deployment of components (dotted lines)
    Docker ---|"deploys"| APIGateway
    Docker ---|"deploys"| Cust
    Docker ---|"deploys"| Vets
    Docker ---|"deploys"| Visits
    Docker ---|"deploys"| GenAI
    Docker ---|"deploys"| Admin
    Docker ---|"deploys"| Discovery
    Docker ---|"deploys"| Config

    %% Class Definitions for Colors
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef service fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click APIGateway "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-api-gateway"
    click Discovery "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-discovery-server"
    click Config "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-config-server"
    click Cust "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-customers-service"
    click Vets "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-vets-service"
    click Visits "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-visits-service"
    click GenAI "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-genai-service"
    click Admin "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/spring-petclinic-admin-server"
    click Prom "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/docker/prometheus"
    click Graf "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/docker/grafana"
    click Chaos "https://github.com/spring-petclinic/spring-petclinic-microservices/tree/main/scripts/chaos"
    click Docker "https://github.com/spring-petclinic/spring-petclinic-microservices/blob/main/docker-compose.yml"
```
