# aarthikrao/timemachine architecture

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

- Interactive diagram: https://gitdiagram.com/aarthikrao/timemachine
- Repository: https://github.com/aarthikrao/timemachine

## Overview

##### Project Type and Purpose
- Type: A distributed, fault-tolerant scheduler database (no user-facing UI, but a cluster of server nodes plus CLI).
- Purpose: Store, route, and execute millions of scheduled jobs across a cluster, using consensus (Raft) for consistency, DHT for load balancing, and B+Tree (BoltDB) for local storage.

##### File Structure
- cmd/cli: Command-line client to interact with the cluster.
- cmd/server: Main server entrypoint, sets up routes and “timeMachine” node.
- components/: Core pluggable modules (consensus, datashard, dht, executor, jobstore, network, routestore).
- handlers/rest: HTTP/REST API layer (cluster, job, route endpoints).
- models/: Protobuf and Go structs for config, jobs, routes.
- process/: Internal controllers (cluster health, connection manager, coordinator, datastore manager, node manager, publisher).
- scripts/: Shell scripts to build, spawn, join, configure cluster nodes.
- utils/: Shared helpers (address, constants, HTTP/gRPC clients, time).

##### README for Additional Insights
- Tech stack callouts: BBoltDB, Raft, DHT, gRPC.
- Workflow: scripts create local folders, spawn multiple instances, nodes join to form a cluster, configure slot distribution, monitor status.
- Documentation links to deeper architecture and component details under docs/ and components/.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        CLI["CLI Client"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        ClusterAPI["Cluster API (handlers/rest/cluster.go)"]:::api
        JobAPI["Job API (handlers/rest/job.go)"]:::api
        RouteAPI["Route API (handlers/rest/route.go)"]:::api
    end

    %% Process Controllers
    subgraph "Process Controllers"
        ClusterHealth["Cluster Health"]:::controller
        ConnectionManager["Connection Manager"]:::controller
        Coordinator["Coordinator"]:::controller
        DatastoreManager["Datastore Manager"]:::controller
        NodeManager["Node Manager"]:::controller
        Publisher["Publisher"]:::controller
    end

    %% Core Modules
    subgraph "Core Modules"
        Consensus["Consensus Module (Raft)"]:::module
        DHT["DHT Module"]:::module
        DataShard["Data Shard & WAL"]:::module
        Executor["Executor"]:::module
        JobStore["JobStore"]:::module
        RouteStore["RouteStore"]:::module
        Network["Network (gRPC)"]:::network
    end

    %% Storage
    subgraph "Local Persistence"
        BoltDB["BoltDB Shard Store"]:::storage
        WAL["Write-Ahead Log"]:::storage
    end

    %% Cluster Peers
    subgraph "Cluster Peers"
        Peer["TimeMachine Node"]:::external
    end

    %% Relationships
    CLI -->|"REST/gRPC"| ClusterAPI
    ClusterAPI -->|delegates| ClusterHealth
    ClusterAPI -->|delegates| Coordinator
    ClusterAPI -->|delegates| ConnectionManager
    ClusterAPI -->|delegates| DatastoreManager
    ClusterAPI -->|delegates| NodeManager
    ClusterAPI -->|delegates| Publisher

    Coordinator -->|log replication| Consensus
    ClusterHealth -.->|heartbeat| Peer
    ConnectionManager -.->|monitor| Peer
    Consensus <-->|"gRPC Mesh"| Peer
    Consensus -->|apply logs| DataShard
    DataShard -->|stores| BoltDB
    DataShard -->|writes| WAL
    Coordinator -->|lookup| DHT
    Executor -->|fetch tasks| JobStore
    Executor -->|fetch routes| RouteStore
    JobStore -->|persist jobs| DataShard
    RouteStore -->|persist routes| DataShard
    Publisher -->|notify| Subscriber[Subscribers]:::external

    %% Click Events
    click CLI "https://github.com/aarthikrao/timemachine/blob/main/cmd/cli/cli.go"
    click ClusterAPI "https://github.com/aarthikrao/timemachine/blob/main/handlers/rest/cluster.go"
    click JobAPI "https://github.com/aarthikrao/timemachine/blob/main/handlers/rest/job.go"
    click RouteAPI "https://github.com/aarthikrao/timemachine/blob/main/handlers/rest/route.go"
    click ClusterHealth "https://github.com/aarthikrao/timemachine/blob/main/process/clusterhealth/clusterhealth.go"
    click ConnectionManager "https://github.com/aarthikrao/timemachine/blob/main/process/connectionmanager/connection_manager.go"
    click Coordinator "https://github.com/aarthikrao/timemachine/blob/main/process/cordinator/cordinator.go"
    click DatastoreManager "https://github.com/aarthikrao/timemachine/blob/main/process/datastoremanager/datastore_manager.go"
    click NodeManager "https://github.com/aarthikrao/timemachine/blob/main/process/nodemanager/node_manager.go"
    click Publisher "https://github.com/aarthikrao/timemachine/blob/main/process/publisher/publisher.go"
    click Consensus "https://github.com/aarthikrao/timemachine/blob/main/components/consensus/consensus.go"
    click DHT "https://github.com/aarthikrao/timemachine/blob/main/components/dht/dht.go"
    click DataShard "https://github.com/aarthikrao/timemachine/blob/main/components/datashard/datashard.go"
    click Executor "https://github.com/aarthikrao/timemachine/blob/main/components/executor/executor.go"
    click JobStore "https://github.com/aarthikrao/timemachine/blob/main/components/jobstore/jobstore.go"
    click RouteStore "https://github.com/aarthikrao/timemachine/blob/main/components/routestore/routestore.go"
    click Network "https://github.com/aarthikrao/timemachine/blob/main/components/network/server/server.go"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px
    classDef api fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef controller fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef module fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#EEE8AA,stroke:#333,stroke-width:1px
    classDef network fill:#DDA0DD,stroke:#333,stroke-width:1px
```
