# karchevskii/disributed_systems architecture

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

- Interactive diagram: https://gitdiagram.com/karchevskii/disributed_systems
- Repository: https://github.com/karchevskii/disributed_systems

## Overview

##### Project type and purpose
- This is a cloud-native, microservice-based full-stack application (“Distributed Tictactoe”) with:
- A Vue.js SPA frontend
- Three backend FastAPI services: Users-Service, Game-Service, Game History-Service
- Supporting infrastructure: Redis cluster, two PostgreSQL clusters
- Deployed via Kubernetes with Istio service mesh

##### File structure
- Top-level folders:
- frontend/ – Vue.js SPA, Dockerfile, Nginx, WebSocket support
- users/ – FastAPI user management, OAuth2, PostgreSQL, migrations
- game/ – FastAPI game logic, WebSockets, Redis, event stream
- game-history/ – FastAPI consumer of Redis Streams, PostgreSQL
- k8s/ – Kubernetes manifests, Istio setup, secrets, ingress, services, deployments
- Patterns: each microservice is containerized, has its own Dockerfile, config, and dependency manifest (requirements.txt).
- Observability, Service Mesh and CI/CD at top level: .github/workflows/ci.yaml

##### README for architecture insights
- Confirms microservice paradigm, real-time via WebSockets, event-driven with Redis Streams
- Istio Ingress Gateway, VirtualServices, Envoy sidecars
- Data stores: Redis for state and streams; CloudNativePG PostgreSQL clusters for persistence
- Observability: Prometheus, Grafana, Kiali, Jaeger

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Browser / Vue.js SPA"]:::client
    click Client "https://github.com/karchevskii/disributed_systems/tree/main/frontend/"

    %% Ingress Gateway
    Gateway["Istio Ingress Gateway\n(Envoy)"]:::mesh

    Client -->|"HTTP/HTTPS\nWebSocket"| Gateway

    %% Service Layer
    subgraph "tictactoe namespace"
        direction TB
        subgraph Services
            direction TB
            UsersProxy["Envoy Sidecar"]:::mesh
            UsersService["Users-Service Pod"]:::service
            GameProxy["Envoy Sidecar"]:::mesh
            GameService["Game-Service Pod"]:::service
            HistoryProxy["Envoy Sidecar"]:::mesh
            HistoryService["Game-History-Service Pod"]:::service
        end
    end

    %% Mesh traffic
    Gateway -->|"REST / WebSocket"| UsersProxy
    UsersProxy -->|loopback| UsersService
    Gateway -->|"REST / WebSocket"| GameProxy
    GameProxy -->|loopback| GameService
    Gateway -->|"REST / WebSocket"| HistoryProxy
    HistoryProxy -->|loopback| HistoryService

    click UsersService "https://github.com/karchevskii/disributed_systems/blob/main/users/app/main.py"
    click GameService "https://github.com/karchevskii/disributed_systems/blob/main/game/app/main.py"
    click HistoryService "https://github.com/karchevskii/disributed_systems/blob/main/game-history/app/main.py"

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Redis["Redis Cluster\n(state & Streams)"]:::db
        PostgresUsers["PostgreSQL Cluster\n(Users)"]:::db
        PostgresHistory["PostgreSQL Cluster\n(Game History)"]:::db
    end

    GameService -->|"Redis (state/events)"| Redis
    HistoryService -->|"Redis Streams" | Redis
    UsersService -->|"SQL (Postgres)"| PostgresUsers
    HistoryService -->|"SQL (Postgres)"| PostgresHistory

    %% Observability & Control Plane
    subgraph "Istio Control Plane"
        istiod["istiod"]:::control
    end
    subgraph Observability
        direction TB
        Prometheus["Prometheus"]:::obs
        Grafana["Grafana"]:::obs
        Kiali["Kiali"]:::obs
        Jaeger["Jaeger"]:::obs
    end

    UsersService -->|"metrics/traces"| Prometheus
    GameService -->|"metrics/traces"| Prometheus
    HistoryService -->|"metrics/traces"| Prometheus
    Prometheus --> Grafana
    Prometheus --> Kiali
    UsersService -->|"traces"| Jaeger
    GameService -->|"traces"| Jaeger
    HistoryService -->|"traces"| Jaeger

    istiod --> UsersProxy
    istiod --> GameProxy
    istiod --> HistoryProxy
    istiod --> Gateway

    %% CI/CD Pipeline
    CI["GitHub Actions CI/CD"]:::infra
    click CI "https://github.com/karchevskii/disributed_systems/blob/main/.github/workflows/ci.yaml"
    CI --> Gateway

    %% Kubernetes Manifests
    k8s["Kubernetes Manifests & Istio Setup"]:::infra
    click k8s "https://github.com/karchevskii/disributed_systems/tree/main/k8s/"
    k8s --> Gateway
    k8s --> istiod
    k8s --> UsersService
    k8s --> GameService
    k8s --> HistoryService

    %% Legend / Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef service fill:#ccf,stroke:#333,stroke-width:2px
    classDef mesh fill:#cfc,stroke:#333,stroke-width:2px
    classDef db fill:#fcf,stroke:#333,stroke-width:2px
    classDef control fill:#cff,stroke:#333,stroke-width:2px
    classDef obs fill:#ffc,stroke:#333,stroke-width:2px
    classDef infra fill:#eef,stroke:#333,stroke-width:2px
```
