# thclab/keriox architecture

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

- Interactive diagram: https://gitdiagram.com/thclab/keriox
- Repository: https://github.com/thclab/keriox

## Overview

##### Main Components
- Core Library (keriox_core): This module contains the foundational mechanics such as event processing, database management (using modules like “redb”, “sled”, etc.), key and prefix management, query handling, and transport (HTTP, default, testing). It is the central piece upon which the other components depend.
- Components:
– Controller (components/controller): Acts as a client for accessing the infrastructure. It manages configuration, communication, and identifier-related operations.
– Watcher (components/watcher): Provides services like HTTP routing, monitoring, and watcher-specific logic. It listens for events and routes updates.
– Witness (components/witness): Functions as the entity that processes/witnesses events in the KERI protocol.
- Support Modules:
– Teliox (support/teliox): Provides additional functionalities related to event processing, state management, transport, and error handling.
– Gossip (support/gossip): Likely adds a layer for network gossip communication among nodes.
- Testing and Examples:
– Kernel tests (keriox_tests) and integration tests show how these components interact in real scenarios.
- CI/CD and Deployment Files:
– The .github/workflows, Dockerfiles (watcher.Dockerfile, witness.Dockerfile), and build scripts provide insight into how the application is built, tested, and deployed.

##### Component Relationships and Interactions
- The core library (keriox_core) is the foundation for handling low-level protocol functionalities such as key management, event generation, and database interaction.
- The Controller is an interface for client interaction (CLI-based or via FFI bindings), while the Watcher and Witness represent operational roles (event listening, processing, and signing) in the protocol.
- Additionally, show external integrations – for instance, clients (Rust, CLI via dkms-bin, or FFI bindings) connect to the Controller, and infrastructure services (such as those deployed via ambient-infrastructure or via Docker) interact with the Watcher and Witness services.

##### Architectural Patterns and Design Principles
- Modularity: The directory structure clearly separates concerns. Each primary role (controller, watcher, witness) is isolated into its own component, while the keriox_core acts as a shared library.
- Layered Architecture: There is a separation between the protocol core (data/event management, database interaction, transport) and the business logic in each component which extends that core functionality.
- Extensibility: Support modules are available to plug in additional functionalities like gossip communication or tel event generation.
- Testing & CI/CD: Multiple testing modules, integration tests, and GitHub workflows indicate a design that emphasizes continuous integration and safe deployment practices.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Library
    Core["Core Library: keriox_core (Database, Event, Keys, Transport)"]:::core

    %% Service Components
    Controller["Controller Component"]:::service
    Watcher["Watcher Component"]:::service
    Witness["Witness Component"]:::service

    %% Support Modules
    Teliox["Teliox Support Module"]:::support
    Gossip["Gossip Support Module"]:::support

    %% External Interfaces
    ExternalClient["External Client (CLI/FFI)"]:::external
    Infrastructure["Deployment Infrastructure"]:::external

    %% Dependencies between components and core library
    Controller -->|"utilizes"| Core
    Watcher -->|"utilizes"| Core
    Witness -->|"utilizes"| Core

    %% Interaction between Controller and Witness for command and event processing
    Controller <-->|"commands_events"| Witness

    %% Support modules extending core functionalities
    Teliox -->|"extends"| Core
    Gossip -->|"extends"| Core

    %% External Interfaces interactions
    ExternalClient -->|"interacts"| Controller
    Infrastructure -->|"integrates"| Watcher
    Infrastructure -->|"integrates"| Witness

    %% Click Events for Component Mapping
    click Core "https://github.com/thclab/keriox/tree/master/keriox_core/"
    click Controller "https://github.com/thclab/keriox/tree/master/components/controller/"
    click Watcher "https://github.com/thclab/keriox/tree/master/components/watcher/"
    click Witness "https://github.com/thclab/keriox/tree/master/components/witness/"
    click Teliox "https://github.com/thclab/keriox/tree/master/support/teliox/"
    click Gossip "https://github.com/thclab/keriox/tree/master/support/gossip/"

    %% Styles
    classDef core fill:#a3c4f3,stroke:#1f77b4,stroke-width:2px;
    classDef service fill:#b2d8b2,stroke:#2ca02c,stroke-width:2px;
    classDef support fill:#d1a3f3,stroke:#9467bd,stroke-width:2px;
    classDef external fill:#f3d1a3,stroke:#ff7f0e,stroke-width:2px;
```
