# gubscruz/platform architecture

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

- Interactive diagram: https://gitdiagram.com/gubscruz/platform
- Repository: https://github.com/gubscruz/platform

## Overview

##### Project Type and Purpose
- This is a polyglot microservices reference platform (built primarily with Spring Boot services in Java and one Python “exchange” service) plus a “docs” site built with MkDocs.
- Its goal is to demonstrate microservices patterns (API Gateway, per‐service database, containerization, CI/CD, Kubernetes) and support hands‐on learning via documentation.

##### Top‐Level Components
- API clients (e.g., Web UI, Mobile)
- API Gateway service (“gateway‐service”)
- Core microservices:
- auth‐service (handles login/register + JWT issuance)
- account‐service (manages user accounts)
- order‐service (manages orders/items)
- product‐service (manages product catalog)
- exchange‐service (Python script for currency/rate conversion)
- Databases (one PostgreSQL instance per service, migrations via Flyway)
- CI/CD & Deployment:
- Jenkins pipelines (Jenkinsfiles in each service)
- Docker (Dockerfiles) / Docker Compose (compose.yaml) for local dev
- Kubernetes manifests (k8s/*.yaml) for cloud deployment
- Documentation site (MkDocs + GitHub Pages)

##### Relationships & Data Flows
- Clients → HTTP(s) → API Gateway
- API Gateway:
- Validates/authenticates JWT (via AuthorizationFilter)
- Routes to downstream microservices
- Microservices:
- Each service exposes REST endpoints (Spring Controllers/Resources)
- Services call each other synchronously if required (e.g., order‐service may call product‐service to validate item details)
- exchange‐service can be invoked by order‐service for currency conversion
- Services ↔ Their own PostgreSQL database (isolated schema per service)
- CI/CD:
- Code pushed → Jenkins Pipeline → Docker image build → Push to Registry → Kubernetes rollout
- Documentation:
- MkDocs → serves local preview or deploys to GitHub Pages

##### Architectural Patterns & Design Principles
- Microservices: fine‐grained, service‐per‐business‐capability
- API Gateway Pattern: single entrypoint, cross‐cutting concerns (CORS, auth)
- Database per Service + Flyway for versioned migrations
- Polyglot approach (Java + Python)
- Containerization (Docker) + Orchestration (Kubernetes)
- CI/CD with Jenkinsfiles in each repo submodule
- Infrastructure as code (k8s YAML, Docker Compose, mkdocs.yml)

##### Technologies & Frameworks to Annotate
- Spring Boot, Spring MVC, Spring Data, Flyway
- Python 3 (exchange‐service)
- PostgreSQL
- Docker & Docker Compose
- Kubernetes
- Jenkins (CI pipelines)
- MkDocs (documentation)

##### Step‐by‐Step Construction
3. Behind the Gateway, arrange the five microservices in a row.
6. Surround the service+DB group with a “Kubernetes Cluster” container; annotate that they’re deployed as pods with k8s YAML.
7. Below the cluster, add CI/CD pipeline elements: Jenkins → Docker Registry → Kubernetes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients"
        Web["Web UI"]:::external
        Mobile["Mobile App"]:::external
    end

    Web --> Gateway
    Mobile --> Gateway

    Gateway["API Gateway\n(Spring Boot)"]:::gateway

    subgraph "Kubernetes Cluster"
        style Kubernetes Cluster stroke-dasharray: 5 5
        subgraph "Services"
            Auth["auth-service\n(Spring Boot)"]:::service
            Account["account-service\n(Spring Boot)"]:::service
            Product["product-service\n(Spring Boot)"]:::service
            Order["order-service\n(Spring Boot)"]:::service
            Exchange["exchange-service\n(Python)"]:::service
        end
        subgraph "Databases"
            AuthDB["auth-db\n(PostgreSQL)"]:::db
            AccountDB["account-db\n(PostgreSQL)"]:::db
            ProductDB["product-db\n(PostgreSQL)"]:::db
            OrderDB["order-db\n(PostgreSQL)"]:::db
        end
    end

    Gateway --> Auth
    Gateway --> Account
    Gateway --> Product
    Gateway --> Order
    Gateway --> Exchange

    Auth --> AuthDB
    Account --> AccountDB
    Product --> ProductDB
    Order --> OrderDB

    Order --> Product
    Order --> Exchange

    subgraph "CI/CD & Deployment"
        Jenkins["Jenkins"]:::external
        Registry["Docker Registry"]:::external
        K8s["Kubernetes"]:::external
        Jenkins --> Registry
        Registry --> K8s
    end

    subgraph "Documentation"
        MkDocs["MkDocs"]:::external
        GHPages["GitHub Pages"]:::external
        MkDocs --> GHPages
    end

    click Gateway "https://github.com/gubscruz/platform/tree/main/api/gateway-service"
    click Auth "https://github.com/gubscruz/platform/tree/main/api/auth-service"
    click Account "https://github.com/gubscruz/platform/tree/main/api/account-service"
    click Product "https://github.com/gubscruz/platform/tree/main/api/product-service"
    click Order "https://github.com/gubscruz/platform/tree/main/api/order-service"
    click Exchange "https://github.com/gubscruz/platform/tree/main/api/exchange-service"
    click Jenkins "https://github.com/gubscruz/platform/blob/main/jenkins/compose.yaml"
    click MkDocs "https://github.com/gubscruz/platform/blob/main/mkdocs.yml"
    click GHPages "https://github.com/gubscruz/platform/tree/main/docs/"

    classDef gateway fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
