# richardktran/kootha architecture

> Architecture diagram of the GitHub repository richardktran/kootha, 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/richardktran/kootha
- Repository: https://github.com/richardktran/kootha

## Overview

- id-generation-service – focused on ID generation with both HTTP and gRPC endpoints.
- quiz-session-service – which handles quiz session logic, includes both API gateway components for calling the id-generation service, in-memory and PostgreSQL repositories, and workers that process messages/events.
- user-service – responsible for user management with its own gRPC and HTTP handlers and similar internal structures seen in the other services.

Additionally, shared libraries and utilities are located in the pkg directory (e.g., discovery and message-broker wrappers) that enable interactions with Consul and Kafka. The api folder contains .proto files that serve as the API contracts for gRPC communication between services.

##### Main Components
- Frontline Services: Represent each microservice (id-generation-service, quiz-session-service, and user-service) as distinct nodes.
- API Layer: Indicate that these services expose gRPC endpoints (and in some cases, HTTP endpoints) with their respective protocol buffers definition (shown in the api directory).
- Data Persistence: Highlight PostgreSQL as a datastore used by at least quiz-session-service (and potentially others).
- Utility Components: Include shared utilities or libraries (grpcutil and discovery modules) that help glue services together.

##### Relationships and Interactions
- GRPC communication flows between services – for instance, quiz-session-service calling id-generation-service via a dedicated gateway (as seen in its internal/gateway/idgeneration).
- HTTP interactions where relevant (since there are HTTP handlers in id-generation-service and user-service).
- Service discovery interactions with Consul, indicating that services register/discover endpoints using the pkg/discovery modules.

##### Architectural Patterns and Design Principles
- Microservices: The project is clearly divided into isolated services that operate independently.
- API-Driven Communication: gRPC and Protobuf form the backbone for inter-service communication.
- Layered Components: Each service is organized into CMD (entry points), internal (handlers, service logic, repositories), and pkg (shared utilities/models) which suggests a clean separation of concerns.
- Event-Driven: The inclusion of message brokers (Kafka) suggests that asynchronous, event-driven patterns are employed.
- Service Discovery: The use of Consul emphasizes dynamic configuration and service registration.

##### Detail Orientation
- Avoid overcomplicating by only representing essential elements – the primary goal is clarity of communication between components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        CONSUL("Hashicorp Consul (Service Discovery)"):::external
        KAFKA("Kafka Message Broker"):::external
        RABBITMQ("RabbitMQ(Optional)"):::external
        PG_DB("PostgreSQL Database"):::database
    end

    subgraph "Shared Utilities"
        API("gRPC API Contracts (.proto)"):::shared
        DISC_CONSUL("Consul Integration"):::shared
        DISC_MAIN("Discovery Utils"):::shared
        GRPC_UTIL("gRPC Utilities"):::shared
        MB("Message Broker Integration"):::shared
    end

    subgraph "id-generation-service"
        IDSVC("HTTP & gRPC Endpoints"):::service
    end

    subgraph "quiz-session-service"
        QSGATEWAY("API Gateway(calls id-gen)"):::service
        QSL("Business Logic"):::service
        Q_INMEM("In-Memory Repository"):::service
        Q_PG("PostgreSQL Repository"):::service
        Q_WORKER("Message Workers"):::service
    end

    subgraph "user-service"
        USER("HTTP/gRPC Handlers"):::service
    end

    %% Communication between services
    QSGATEWAY -->|"gRPC_call"| IDSVC

    %% Service Discovery Registration
    IDSVC -->|"register/discover"| CONSUL
    QSGATEWAY -->|"register/discover"| CONSUL
    USER -->|"register/discover"| CONSUL

    %% Message Flows in Quiz Session Service
    Q_WORKER -->|"publish/consume"| KAFKA
    Q_WORKER -->|"publish/consume"| RABBITMQ

    %% Data Flow - Persistence
    Q_PG -->|"data_access"| PG_DB

    %% Utilization of Shared Utilities
    IDSVC -->|"uses"| GRPC_UTIL
    USER  -->|"uses"| GRPC_UTIL
    IDSVC -->|"defines"| API
    QSGATEWAY -->|"uses"| API
    USER  -->|"uses"| API

    DISC_CONSUL --> CONSUL
    DISC_MAIN   --> CONSUL
    Q_WORKER -->|"uses"| MB

    %% Click Events
    click IDSVC "https://github.com/richardktran/kootha/tree/main/id-generation-service/"
    click QSGATEWAY "https://github.com/richardktran/kootha/tree/main/quiz-session-service/"
    click USER "https://github.com/richardktran/kootha/tree/main/user-service/"
    click API "https://github.com/richardktran/kootha/tree/main/api/"
    click DISC_CONSUL "https://github.com/richardktran/kootha/blob/main/pkg/discovery/consul/consul.go"
    click DISC_MAIN "https://github.com/richardktran/kootha/blob/main/pkg/discovery/discovery.go"
    click MB "https://github.com/richardktran/kootha/tree/main/pkg/message-broker/"
    click PG_DB "https://github.com/richardktran/kootha/blob/main/docker/postgres/docker-compose.yml"
    click GRPC_UTIL "https://github.com/richardktran/kootha/tree/main/utils/grpcutil/"

    %% Styling
    classDef service fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef external fill:#ffa07a,stroke:#cd5c5c,stroke-width:2px;
    classDef database fill:#98fb98,stroke:#008000,stroke-width:2px;
    classDef shared fill:#ffffe0,stroke:#ffd700,stroke-width:2px;
```
