# moclojer/chrondb architecture

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

## Overview

##### Project Type & Purpose
- ChronDB is a database engine that stores immutable and atomic key/value data in a Git-inspired manner with built-in support for REST, Redis, and SQL protocols.
- It is meant both as a backend service (delivering API endpoints and direct data operations) and as a highly configurable, chronologically versioned store, making its architecture critical for performance and reliability.

##### Main Components
a. API Protocol Layers:
- REST API Server: Handles HTTP requests (evidenced by src/chrondb/api, src/chrondb/api/v1 and sample usage in the README).
- Redis Protocol Server: Implements Redis driver compatibility (see src/chrondb/api/redis and associated tests).
- SQL Interface: Provides SQL compliance via query execution, parsing, and protocol handling (review src/chrondb/api/sql for parser, execution, and protocol handlers).

b. Core Engine:
- Core Module: Implements the fundamental logic, including document storage and retrieval. This resides in src/chrondb/core.
- Repository and Storage Subsystems:
- Git-Based Storage: Uses Git concepts to track changes, maintain history, and support operations like checkout, revert, and merge (refer to the README’s explanation and src/chrondb/storage with git implementations).
- Memory-based Storage: Alternative in-memory storage implemented along with Git (see src/chrondb/storage/memory).
- Indexing: Integration with Lucene and in-memory indexing (see src/chrondb/index).
- Tools: Utilities for diagnostics, migrators, and dumping data (src/chrondb/tools).

c. Configuration and Logging:
- Configuration: Managed via EDN files (config.example.edn, config.edn) and the config namespace (src/chrondb/config.clj) to set up Git, storage, and logging options.
- Logging: Configured to output to stdout or file, with adjustable log levels (src/chrondb/util/logging.clj and resources/log4j.properties).

##### Relationships and Interactions
- External clients (or testing tools) interact via three major protocols:
- HTTP clients call into the REST API server.
- Clients using Redis drivers communicate with the Redis protocol server.
- SQL clients interact through the SQL interface.
- Each API entry point communicates with the core engine, which encapsulates:
- The repository layer (Git structure)
- The data storage layer (backed by either Git or memory storage)
- The indexing layer (for rapid query responses using Lucene)
- The configuration module initializes runtime settings that influence the behavior of all these components.
- Tools and utilities like diagnostics and migrators may operate “side-by-side” with core components to manage and inspect the data.

##### Architectural Patterns and Principles
- Modularity: Clear separation of concerns between API protocols, core data storage, indexing, and configuration.
- Extensibility: The project’s design allows enabling or disabling individual services (e.g., using command-line flags to disable REST, Redis, or SQL servers).
- Immutable/Chronological Data Management: Inspired by Git, ensuring that all changes are stored and can be queried historically.
- Use of Functional Programming (in Clojure) to promote immutability and concurrency.

##### Summary of What to Capture
- Start from the external interfaces (HTTP, Redis, SQL) then drill down to how each is connected to the core ChronDB engine.
- Indexing and search operations as part of the processing chain.
- Auxiliary tools and scripts (such as diagnostics and migrators) interacting with the main core but not directly in the regular client flow.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        HTTP["HTTP Client"]:::client
        RedisClient["Redis Client"]:::client
        SQLClient["SQL Client"]:::client
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        REST["REST API Server"]:::api
        RedisAPI["Redis Protocol Server"]:::api
        SQL["SQL Interface"]:::api
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        Core["Core Module"]:::core
        Repository["Repository Layer (Git-Based Storage)"]:::core
        MemoryStorage["Memory-based Storage"]:::core
        Index["Indexing Module (Lucene & Memory)"]:::core
    end

    %% Configuration & Utilities Layer
    subgraph "Configuration & Utilities Layer"
        Config["Configuration Module"]:::config
        Logging["Logging Module"]:::config
        Tools["Tools and Utilities"]:::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Git["Git Library"]:::external
        Lucene["Lucene Library"]:::external
    end

    %% Connections from Clients to API Gateways
    HTTP -->|"calls"| REST
    RedisClient -->|"calls"| RedisAPI
    SQLClient -->|"calls"| SQL

    %% Connections from API Gateways to Core Processing
    REST -->|"processes"| Core
    RedisAPI -->|"processes"| Core
    SQL -->|"processes"| Core

    %% Internal connections within Core Processing Layer
    Core -->|"uses"| Repository
    Core -->|"uses"| MemoryStorage
    Core -->|"indexes with"| Index

    %% Connections from Configuration & Utilities to Core
    Config -->|"configures"| Core
    Logging -->|"monitors"| Core
    Tools -->|"assists"| Core

    %% External dependencies linked to core components
    Repository -->|"integrates"| Git
    Index -->|"leverages"| Lucene

    %% Click Events
    click REST "https://github.com/moclojer/chrondb/blob/main/src/chrondb/api/v1.clj"
    click RedisAPI "https://github.com/moclojer/chrondb/tree/main/src/chrondb/api/redis/"
    click SQL "https://github.com/moclojer/chrondb/tree/main/src/chrondb/api/sql/"
    click Core "https://github.com/moclojer/chrondb/blob/main/src/chrondb/core.clj"
    click Repository "https://github.com/moclojer/chrondb/blob/main/src/chrondb/storage/git.clj"
    click MemoryStorage "https://github.com/moclojer/chrondb/blob/main/src/chrondb/storage/memory.clj"
    click Index "https://github.com/moclojer/chrondb/tree/main/src/chrondb/index/"
    click Tools "https://github.com/moclojer/chrondb/tree/main/src/chrondb/tools/"
    click Config "https://github.com/moclojer/chrondb/blob/main/src/chrondb/config.clj"
    click Logging "https://github.com/moclojer/chrondb/blob/main/src/chrondb/util/logging.clj"

    %% Styles
    classDef client fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef api fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef config fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-dasharray: 5 5,stroke-width:2px;
```
