# hitesh22rana/chronoverse architecture

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

- Interactive diagram: https://gitdiagram.com/hitesh22rana/chronoverse
- Repository: https://github.com/hitesh22rana/chronoverse

## Overview

##### Main Components
a. Core API & Services:
- API Gateway (“Server”): Located in cmd/server and internal/server. This handles client requests, authentication (using JWT as seen in internal/pkg/auth), and routing to appropriate services.
- Users Service: Found under cmd/users-service with supporting business logic in internal/app/users, internal/service/users, and related repository code. It manages authentication, authorization, and user profiles.
- Workflows Service: Seen in cmd/workflows-service along with its internal implementations. It manages the creation, update, and configuration of workflow definitions.
- Jobs Service: Present as cmd/jobs-service with supporting modules in internal/app/jobs and internal/service/jobs. This service manages scheduled job instances and their lifecycle.

b. Worker Components:
- Scheduling Worker: (cmd/scheduling-worker and internal/app/scheduler) Responsible for reading schedules (for example, based on cron expressions) and determining when jobs should be executed.
- Workflow Worker: (cmd/workflow-worker, internal/app/workflow) Prepares and builds jobs prior to their execution.
- Execution Worker: (cmd/execution-worker, internal/app/executor) In charge of running jobs in isolated environments (leveraging container functionality from internal/pkg/kind/container).
- Joblogs Processor: (cmd/joblogs-processor, internal/app/joblogs) Manages logging and state changes of job executions.

c. Integration & Shared Components:
- Communication / Messaging: The system uses Kafka (internal/pkg/kafka) to enable reliable messaging between the services and workers.
- Databases:
– Postgres: Handles core transactional data (users, workflows, jobs). Look for migrations and repository code in internal/pkg/postgres.
– ClickHouse: Likely used for high-speed ingestion and querying of job logs (internal/pkg/clickhouse).
- Observability: OpenTelemetry integrations (internal/pkg/otel) are used to trace and monitor distributed processes.
- Shared utilities: Common libraries for logging (internal/pkg/logger), crypto (internal/pkg/crypto), and configurations (internal/config).

##### Relationships and Interactions
- The API Gateway receives client calls (possibly via HTTP or gRPC given the protobuf definitions in pkg/proto) and routes them to the relevant service (Users, Workflows, Jobs).
- Upon scheduling, the Scheduling Worker identifies due jobs and signals the Workflow and Execution Workers to start processing.
- After running a job, log data is gathered and processed by the Joblogs Processor.
- The services and workers communicate via a message broker (Kafka) to ensure asynchronous, reliable messaging.
- Each service and worker loads configuration from internal/config files; these configurations are environment-variable driven (as noted in the README and docker-compose.yaml).
- Common functionalities such as authentication, logging, and error handling are abstracted into internal/pkg modules.

##### Architectural Patterns and Design Principles
- Microservices Architecture: Each component (API gateway, core services, workers) is independently deployable, containerized (using Docker and orchestrated with docker-compose).
- Separation of Concerns: Business logic is segmented among different service folders (internal/app, internal/service) and further decoupled through dedicated workers.
- Message-driven Communication: Utilizes Kafka to decouple services and ensure fault tolerance.
- Observability and Security: Built-in support for tracing (with OTEL) and JWT-based authentication.
- Use of Code Generation: The presence of buf.yaml and the proto directories indicate that protobuf and gRPC are used for inter-service communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API & Core Services
    subgraph "API & Core Services"
        Clients("Clients"):::client
        API_Gateway("API Gateway (Server)"):::api
        Users("Users Service"):::api
        Workflows("Workflows Service"):::api
        Jobs("Jobs Service"):::api

        Clients -->|"HTTP/gRPC"| API_Gateway
        API_Gateway -->|"routes"| Users
        API_Gateway -->|"routes"| Workflows
        API_Gateway -->|"routes"| Jobs
    end

    %% Worker Components
    subgraph "Worker Components"
        SchedulingWorker("Scheduling Worker"):::worker
        WorkflowWorker("Workflow Worker"):::worker
        ExecutionWorker("Execution Worker"):::worker
        JoblogsProcessor("Joblogs Processor"):::worker

        SchedulingWorker -->|"triggers"| WorkflowWorker
        SchedulingWorker -->|"triggers"| ExecutionWorker
        ExecutionWorker -->|"logs"| JoblogsProcessor
    end

    %% External Systems and Integrations
    subgraph "External Systems"
        Kafka("Messaging Broker (Kafka)"):::integration
        Postgres("Database (Postgres)"):::integration
        ClickHouse("Database (ClickHouse)"):::integration
        Observability("Observability (OpenTelemetry)"):::integration
        SharedUtils("Shared Utilities (Auth,Logging,Crypto)"):::integration
    end

    %% Messaging connections (asynchronous communication)
    Users -->|"async"| Kafka
    Workflows -->|"async"| Kafka
    Jobs -->|"async"| Kafka
    SchedulingWorker -->|"async"| Kafka
    WorkflowWorker -->|"async"| Kafka
    ExecutionWorker -->|"async"| Kafka
    JoblogsProcessor -->|"async"| Kafka

    %% Database operations
    Users -->|"db_ops"| Postgres
    Workflows -->|"db_ops"| Postgres
    Jobs -->|"db_ops"| Postgres
    JoblogsProcessor -->|"writes"| ClickHouse

    %% Observability tracing
    API_Gateway -->|"trace"| Observability
    Users -->|"trace"| Observability
    Workflows -->|"trace"| Observability
    Jobs -->|"trace"| Observability
    SchedulingWorker -->|"trace"| Observability
    WorkflowWorker -->|"trace"| Observability
    ExecutionWorker -->|"trace"| Observability
    JoblogsProcessor -->|"trace"| Observability

    %% Shared utilities usage
    API_Gateway -->|"util"| SharedUtils
    Users -->|"util"| SharedUtils
    Workflows -->|"util"| SharedUtils
    Jobs -->|"util"| SharedUtils
    SchedulingWorker -->|"util"| SharedUtils
    WorkflowWorker -->|"util"| SharedUtils
    ExecutionWorker -->|"util"| SharedUtils
    JoblogsProcessor -->|"util"| SharedUtils

    %% Click Events for Component Mappings
    click API_Gateway "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/server"
    click Users "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/users-service"
    click Workflows "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/workflows-service"
    click Jobs "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/jobs-service"
    click SchedulingWorker "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/scheduling-worker"
    click WorkflowWorker "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/workflow-worker"
    click ExecutionWorker "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/execution-worker"
    click JoblogsProcessor "https://github.com/hitesh22rana/chronoverse/tree/main/cmd/joblogs-processor"
    click Kafka "https://github.com/hitesh22rana/chronoverse/tree/main/internal/pkg/kafka"
    click Postgres "https://github.com/hitesh22rana/chronoverse/tree/main/internal/pkg/postgres"
    click ClickHouse "https://github.com/hitesh22rana/chronoverse/tree/main/internal/pkg/clickhouse"
    click Observability "https://github.com/hitesh22rana/chronoverse/tree/main/internal/pkg/otel"
    click SharedUtils "https://github.com/hitesh22rana/chronoverse/tree/main/internal/pkg/auth"

    %% Styles
    classDef api fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef worker fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef integration fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef client fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
```
