# flashhhhh/vcs-sms architecture

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

- Interactive diagram: https://gitdiagram.com/flashhhhh/vcs-sms
- Repository: https://github.com/flashhhhh/vcs-sms

## Overview

##### Project type and purpose
- This project, “VCS-SMS,” is a Go-based microservices system (with a bit of Python orchestration via main.py).
- It provides user management (user_service), server administration (server_administration_service), email notifications (mail_service), health‐checking capabilities (healthcheck_service), and a fake server simulator (fake_server_service).
- Each service exposes REST and/or gRPC APIs, owns its own datastore (Postgres, Redis, Elasticsearch, etc.), and communicates via gRPC or Kafka.

##### File structure
- Top-level services:
- fake_server_service
- healthcheck_service
- mail_service
- server_administration_service
- user_service
- Common patterns:
- cmd/ – entry points (REST, gRPC, Kafka)
- api/ – HTTP middlewares & routes
- infrastructure/ – adapters for databases, caches, brokers, gRPC servers/clients
- internal/ – service/business logic, handlers, repositories, DTOs/domain models
- proto/pb – Protocol Buffer definitions & stubs
- deployments/docker & kubernetes – containerization artifacts
- Shared artifacts: docker-compose.yml (orchestration), OpenAPI specs in docs/, swagger-config.yaml

##### Key architectural characteristics
- Microservices, each isolated in its own Git module, container, and deployment.
- Polyglot inter-service comms: HTTP+REST for external API, gRPC for high-performant internal RPC, Kafka for eventing.
- Each service typically uses Postgres for primary storage, Redis for caching or pub/sub, and Elasticsearch for search (server_administration).
- Healthcheck service polls or receives health-status data via gRPC.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        Clients["Clients\n(Admin UI, User UI, Monitoring Tools)"]:::external
    end

    %% Orchestration
    subgraph "Orchestration"
        DC["docker-compose.yml"]:::orchestration
        PY["main.py"]:::orchestration
    end

    %% Microservices
    subgraph "Microservices"
        US["user_service"]:::service
        SAS["server_administration_service"]:::service
        MS["mail_service"]:::service
        HCS["healthcheck_service"]:::service
        FSS["fake_server_service"]:::service
    end

    %% Datastores
    subgraph "Datastores"
        PG_US["Postgres (user_service)"]:::db
        PG_SAS["Postgres (server_administration_service)"]:::db
        PG_MS["Postgres (mail_service)"]:::db
        PG_HCS["Postgres (healthcheck_service)"]:::db
        PG_FSS["Postgres (fake_server_service)"]:::db
        ES["Elasticsearch"]:::db
    end

    %% Caches & Messaging
    subgraph "Caches & Messaging"
        REDIS_US["Redis (user_service)"]:::cache
        REDIS_SAS["Redis (server_administration_service)"]:::cache
        REDIS_HCS["Redis (healthcheck_service)"]:::cache
        REDIS_FSS["Redis (fake_server_service)"]:::cache
        KAFKA["Kafka Cluster"]:::messaging
    end

    %% Connections - Clients to Services
    Clients -->|"REST"| US
    Clients -->|"REST"| SAS

    %% Orchestration to Services
    DC --> US
    DC --> SAS
    DC --> MS
    DC --> HCS
    DC --> FSS
    PY --> US
    PY --> SAS
    PY --> MS
    PY --> HCS
    PY --> FSS

    %% Service to Messaging
    SAS -->|"Kafka"| KAFKA
    KAFKA -->|"consume"| MS

    %% Service to Service gRPC
    MS -->|"gRPC"| US
    MS -->|"gRPC"| SAS
    HCS -->|"gRPC"| SAS
    HCS -->|"gRPC"| FSS

    %% Service to Cache
    FSS -->|"Redis pub/sub"| REDIS_FSS

    %% Service to Databases
    US -->|"CRUD"| PG_US
    SAS -->|"CRUD"| PG_SAS
    MS -->|"CRUD"| PG_MS
    HCS -->|"CRUD"| PG_HCS
    FSS -->|"CRUD"| PG_FSS

    %% Additional Infra
    SAS -->|"index/search"| ES

    %% Click Events
    click US "https://github.com/flashhhhh/vcs-sms/tree/main/user_service/"
    click SAS "https://github.com/flashhhhh/vcs-sms/tree/main/server_administration_service/"
    click MS "https://github.com/flashhhhh/vcs-sms/tree/main/mail_service/"
    click HCS "https://github.com/flashhhhh/vcs-sms/tree/main/healthcheck_service/"
    click FSS "https://github.com/flashhhhh/vcs-sms/tree/main/fake_server_service/"
    click DC "https://github.com/flashhhhh/vcs-sms/blob/main/docker-compose.yml"
    click PY "https://github.com/flashhhhh/vcs-sms/blob/main/main.py"
    click PG_US "https://github.com/flashhhhh/vcs-sms/blob/main/user_service/infrastructure/postgres/main.go"
    click REDIS_US "https://github.com/flashhhhh/vcs-sms/blob/main/user_service/infrastructure/redis/main.go"
    click US "https://github.com/flashhhhh/vcs-sms/blob/main/user_service/cmd/server/rest/main.go"
    click SAS "https://github.com/flashhhhh/vcs-sms/blob/main/server_administration_service/cmd/server/rest/main.go"
    click MS "https://github.com/flashhhhh/vcs-sms/blob/main/mail_service/cmd/server/main.go"
    click HCS "https://github.com/flashhhhh/vcs-sms/blob/main/healthcheck_service/cmd/main.go"
    click FSS "https://github.com/flashhhhh/vcs-sms/blob/main/fake_server_service/cmd/main.go"
    click ES "https://github.com/flashhhhh/vcs-sms/blob/main/server_administration_service/infrastructure/elasticsearch/elasticsearch.go"

    %% Styles
    classDef service fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef db fill:#CFF7AE,stroke:#333,stroke-width:1px
    classDef cache fill:#FFF7AE,stroke:#333,stroke-width:1px
    classDef messaging fill:#F7E0AE,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef orchestration fill:#DEAEF7,stroke:#333,stroke-width:1px
```
