# piomin/sample-spring-microservices-kubernetes architecture

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

- Interactive diagram: https://gitdiagram.com/piomin/sample-spring-microservices-kubernetes
- Repository: https://github.com/piomin/sample-spring-microservices-kubernetes

## Overview

##### Project type and purpose
- This is a Spring Boot/Spring Cloud microservices demo deployed on Kubernetes.
- It showcases:
- An API gateway (Zuul)
- Three domain services (employee, department, organization) with inter-service calls
- A Spring Boot Admin server for monitoring
- MongoDB as the shared database
- Kubernetes deployments, services, config maps, secrets, ingress

##### File structure
- Top-level modules:
- gateway-service
- employee-service
- department-service
- organization-service
- admin-service
- Shared infra folder: `k8s/` contains cluster-wide resources (Ingress, MongoDB manifests, RBAC)
- Each service has:
- A Dockerfile + Skaffold config + Kubernetes manifests (configmap, secret, deployment, service)
- A standard Spring Boot src tree (main/java, resources, tests)
- Root-level `pom.xml` for multi-module build, `.circleci` for CI, `skaffold.yaml` for local dev

##### README insights
- Describes each module’s role and interactions
- Highlights use of:
- Spring Cloud Netflix Zuul (gateway)
- Spring Cloud Kubernetes for discovery/config
- MongoDB as a persistence layer
- Spring Boot Admin for monitoring

a. Main components
- External client/users
- Kubernetes Ingress (routes traffic to gateway-service)
- gateway-service (API Gateway/Zuul)
- employee-service, department-service, organization-service (microservice pods + services)
- admin-service (Spring Boot Admin Server)
- MongoDB cluster (Deployment + Service, backed by Secret and ConfigMap)
- ConfigMap & Secret for each microservice (injected as environment)
b. Relationships & data flows
- Client → Ingress → gateway-service → appropriate microservice
- department-service calls employee-service (via RestTemplate or Feign)
- organization-service calls both employee-service and department-service
- All services connect to MongoDB service for persistence
- admin-service scrapes health/metrics endpoints of all microservices
c. Architectural patterns & design principles
- API Gateway pattern
- Service discovery (via Kubernetes + Spring Cloud Kubernetes)
- Externalized configuration (ConfigMap & Secret)
- Poly-service database (each service has its own MongoDB collection, but same cluster)
- CI/CD integration (Skaffold, CircleCI)
d. Key technologies & libraries
- Spring Boot 2.x, Spring Cloud Netflix Zuul
- Spring Cloud Kubernetes (DiscoveryClient, Ribbon)
- Spring Boot Admin
- MongoDB Java driver / Spring Data MongoDB
- Docker, Kubernetes (Deployments, Services, Ingress, ConfigMap, Secret)
- Maven, Skaffold, CircleCI

##### Elements
- Clear, human-readable labels on every component (e.g., “gateway-service”, “employee-service”)
- External request flow (Ingress → Gateway → Microservices)
- Inter-service calls
- Database read/write
- Monitoring scrapes by admin-service
- Gateway (e.g., blue rectangle)
- Microservices (e.g., green circles)
- Monitoring (e.g., orange hexagon)
- Annotations for ConfigMaps/Secrets injection into pods
- A cluster boundary to show what runs inside Kubernetes

##### Detailed but not over-complicated
- Common concerns (CI/CD, Skaffold, circleci) separately or as footnotes
- Essential flows, external dependencies, and intra-service interactions
- Avoid over-splitting: focus on logical components rather than every file

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client/User"]:::external
    Client -->|"HTTP Request"| Ingress["Kubernetes Ingress"]:::infra
    subgraph "Kubernetes Cluster"
        style KubernetesCluster fill:none,stroke:#bbb,stroke-dasharray:5 5
        Ingress --> Gateway["gateway-service"]:::gateway
        Gateway --> Employee["employee-service"]:::service
        Gateway --> Department["department-service"]:::service
        Gateway --> Organization["organization-service"]:::service
        Gateway --> Admin["admin-service"]:::monitoring

        Employee -->|"persist/read/write"| MongoDB["MongoDB Cluster"]:::db
        Department -->|"persist/read/write"| MongoDB
        Organization -->|"persist/read/write"| MongoDB

        Department -->|calls Employee API| Employee
        Organization -->|calls Department API| Department
        Organization -->|calls Employee API| Employee

        Admin -->|scrapes /actuator| Gateway
        Admin -->|scrapes /actuator| Employee
        Admin -->|scrapes /actuator| Department
        Admin -->|scrapes /actuator| Organization
    end

    click Gateway "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/gateway-service/src/main/java/pl/piomin/services/gateway/GatewayApplication.java"
    click Employee "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/employee-service/src/main/java/pl/piomin/services/employee/EmployeeApplication.java"
    click Department "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/department-service/src/main/java/pl/piomin/services/department/DepartmentApplication.java"
    click Organization "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/organization-service/src/main/java/pl/piomin/services/organization/OrganizationApplication.java"
    click Admin "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/admin-service/src/main/java/pl/piomin/services/admin/AdminApplication.java"
    click MongoDB "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/k8s/mongodb-deployment.yaml"
    click Ingress "https://github.com/piomin/sample-spring-microservices-kubernetes/blob/master/k8s/ingress.yaml"

    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef infra fill:#dddddd,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef gateway fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef service fill:#98FB98,stroke:#333,stroke-width:1px
    classDef db fill:#FFFACD,stroke:#333,stroke-width:1px,shape:cylinder
    classDef monitoring fill:#FFA500,stroke:#333,stroke-width:1px,shape:hexagon
```
