# fepelus/javaraft architecture

> Architecture diagram of the GitHub repository fepelus/javaraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fepelus/javaraft
- Repository: https://github.com/fepelus/javaraft

## Overview

This repository combines a Raft-based key-value-store application with a vendored KDL parser/model/search library. The main product workflow is a client request handled by the server-side application and replicated through Raft; the README describes Core’s event-in/command-out boundary and the surrounding network, timer, and SQLite integrations. KDL supplies configuration-file support and also provides general parsing, printing, searching, and mutation capabilities. Several Raft implementation files and the configuration wiring were not sampled, so uncertain connections are omitted or marked dashed.

Main entry points: [`src/main/java/com/fepelus/raft/Server.java`](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Server.java) (Server entrypoint), [`src/main/java/kdl/objects/KDLDocument.java`](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLDocument.java) (Document and nodes), [`src/main/java/com/fepelus/raft/Client.java`](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Client.java) (CLI client), [`src/main/java/kdl/parse/KDLParser.java`](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParser.java) (KDL parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_raft["Raft key-value store"]
  node_client["CLI client<br/>[Client.java]"]
  node_server["Server entrypoint<br/>[Server.java]"]
  node_application["KV application<br/>[Application.java]"]
end

subgraph group_runtime["Raft runtime"]
  node_handler["Raft handler<br/>[Handler.java]"]
  node_core["Raft core<br/>[Core.java]"]
  node_events["Events<br/>[Events.java]"]
  node_commands["Commands<br/>[Commands.java]"]
  node_consensus["Consensus interface<br/>[Consensus.java]"]
  node_transport["Network transport<br/>[Transport.java]"]
  node_listener["Network listener<br/>[Listener.java]"]
  node_timer["Election timer<br/>[Timer.java]"]
  node_state[("SQLite state<br/>[SQLiteState.java]")]
  node_config["Configuration<br/>[Config.java]"]
end

subgraph group_kdlparse["KDL parsing and printing"]
  node_kdlparser["KDL parser<br/>[KDLParser.java]"]
  node_kdlcontext["Parse context"]
  node_charclasses["Character rules<br/>[CharClasses.java]"]
  node_parserfacade["Parser facade"]
  node_printer["KDL printer<br/>[PrintUtil.java]"]
  node_printconfig["Print settings<br/>[PrintConfig.java]"]
end

subgraph group_kdlmodel["KDL document model"]
  node_document["Document and nodes<br/>[KDLDocument.java]"]
  node_node["Node structure<br/>[KDLNode.java]"]
  node_values["KDL values<br/>[KDLValue.java]"]
end

subgraph group_kdlsearch["KDL search and mutation"]
  node_search["Document search<br/>[GeneralSearch.java]"]
  node_pathedsearch["Pathed search<br/>[PathedSearch.java]"]
  node_rootsearch["Root search<br/>[RootSearch.java]"]
  node_predicates["Node predicates<br/>[NodePredicate.java]"]
  node_mutations["Tree mutations<br/>[Mutation.java]"]
end

node_user(("Client user"))
node_raftpeers(("Raft peers"))
node_sqlite[("SQLite")]
node_zeromq["JeroMQ"]
node_kdlconfig["KDL config files"]

node_user -->|"issues request"| node_client
node_client -.->|"sends request"| node_server
node_server -->|"configures"| node_application
node_server -->|"starts"| node_handler
node_handler -.->|"drives"| node_core
node_handler -->|"uses timer"| node_timer
node_core -->|"consumes events"| node_events
node_core -->|"emits commands"| node_commands
node_server -->|"configures"| node_consensus
node_server -->|"configures"| node_transport
node_server -->|"configures"| node_listener
node_server -->|"configures"| node_state
node_transport -.->|"exchanges messages"| node_raftpeers
node_state -->|"persists state"| node_sqlite
node_transport -->|"uses messaging"| node_zeromq
node_client -->|"parses KDL"| node_document
node_client -->|"queries nodes"| node_search
node_kdlconfig -.->|"configures"| node_config
node_parserfacade -->|"delegates parsing"| node_kdlparser
node_kdlparser -->|"reads input"| node_kdlcontext
node_kdlparser -->|"checks characters"| node_charclasses
node_kdlparser -->|"builds document"| node_document
node_document -->|"contains nodes"| node_node
node_node -->|"stores values"| node_values
node_document -->|"prints with settings"| node_printconfig
node_node -->|"writes KDL"| node_printer
node_printer -->|"checks escaping"| node_printconfig
node_search -->|"tests nodes"| node_predicates
node_search -->|"applies mutations"| node_mutations
node_search -->|"traverses document"| node_document
node_pathedsearch -->|"tests nodes"| node_predicates
node_rootsearch -->|"applies mutations"| node_mutations

click node_client "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Client.java"
click node_server "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Server.java"
click node_application "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Application.java"
click node_handler "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Handler.java"
click node_core "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Core.java"
click node_events "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Events.java"
click node_commands "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Commands.java"
click node_consensus "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Consensus.java"
click node_transport "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Transport.java"
click node_listener "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Listener.java"
click node_timer "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Timer.java"
click node_state "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/SQLiteState.java"
click node_config "https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Config.java"
click node_kdlparser "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParser.java"
click node_kdlcontext "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParseContext.java"
click node_charclasses "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/CharClasses.java"
click node_parserfacade "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParserFacade.java"
click node_printer "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/print/PrintUtil.java"
click node_printconfig "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/print/PrintConfig.java"
click node_document "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLDocument.java"
click node_node "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLNode.java"
click node_values "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLValue.java"
click node_search "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/GeneralSearch.java"
click node_pathedsearch "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/PathedSearch.java"
click node_rootsearch "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/RootSearch.java"
click node_predicates "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/predicates/NodePredicate.java"
click node_mutations "https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/mutation/Mutation.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_application,node_user toneBlue
class node_handler,node_core,node_events,node_commands,node_consensus,node_transport,node_listener,node_timer,node_state,node_config,node_sqlite toneAmber
class node_kdlparser,node_kdlcontext,node_charclasses,node_parserfacade,node_printer,node_printconfig toneMint
class node_document,node_node,node_values toneRose
class node_search,node_pathedsearch,node_rootsearch,node_predicates,node_mutations,node_raftpeers,node_zeromq,node_kdlconfig toneIndigo
```

## Components

### Raft key-value store

- [CLI client](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Client.java): `src/main/java/com/fepelus/raft/Client.java`
- [Server entrypoint](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Server.java): `src/main/java/com/fepelus/raft/Server.java`
- [KV application](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Application.java): `src/main/java/com/fepelus/raft/Application.java`

### Raft runtime

- [Raft handler](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Handler.java): `src/main/java/com/fepelus/raft/Handler.java`
- [Raft core](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Core.java): `src/main/java/com/fepelus/raft/Core.java`
- [Events](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Events.java): `src/main/java/com/fepelus/raft/Events.java`
- [Commands](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Commands.java): `src/main/java/com/fepelus/raft/Commands.java`
- [Consensus interface](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Consensus.java): `src/main/java/com/fepelus/raft/Consensus.java`
- [Network transport](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Transport.java): `src/main/java/com/fepelus/raft/Transport.java`
- [Network listener](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Listener.java): `src/main/java/com/fepelus/raft/Listener.java`
- [Election timer](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Timer.java): `src/main/java/com/fepelus/raft/Timer.java`
- [SQLite state](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/SQLiteState.java): `src/main/java/com/fepelus/raft/SQLiteState.java`
- [Configuration](https://github.com/fepelus/javaraft/blob/main/src/main/java/com/fepelus/raft/Config.java): `src/main/java/com/fepelus/raft/Config.java`

### KDL parsing and printing

- [KDL parser](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParser.java): `src/main/java/kdl/parse/KDLParser.java`
- [Parse context](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParseContext.java): `src/main/java/kdl/parse/KDLParseContext.java`
- [Character rules](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/CharClasses.java): `src/main/java/kdl/parse/CharClasses.java`
- [Parser facade](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/parse/KDLParserFacade.java): `src/main/java/kdl/parse/KDLParserFacade.java`
- [KDL printer](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/print/PrintUtil.java): `src/main/java/kdl/print/PrintUtil.java`
- [Print settings](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/print/PrintConfig.java): `src/main/java/kdl/print/PrintConfig.java`

### KDL document model

- [Document and nodes](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLDocument.java): `src/main/java/kdl/objects/KDLDocument.java`
- [Node structure](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLNode.java): `src/main/java/kdl/objects/KDLNode.java`
- [KDL values](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/objects/KDLValue.java): `src/main/java/kdl/objects/KDLValue.java`

### KDL search and mutation

- [Document search](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/GeneralSearch.java): `src/main/java/kdl/search/GeneralSearch.java`
- [Pathed search](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/PathedSearch.java): `src/main/java/kdl/search/PathedSearch.java`
- [Root search](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/RootSearch.java): `src/main/java/kdl/search/RootSearch.java`
- [Node predicates](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/predicates/NodePredicate.java): `src/main/java/kdl/search/predicates/NodePredicate.java`
- [Tree mutations](https://github.com/fepelus/javaraft/blob/main/src/main/java/kdl/search/mutation/Mutation.java): `src/main/java/kdl/search/mutation/Mutation.java`

### Other components

- **Client user**
- **Raft peers**
- **SQLite**
- **JeroMQ**
- **KDL config files**

## Connections

- Client user → CLI client: issues request
- CLI client → Server entrypoint: sends request
- Server entrypoint → KV application: configures (evidence: `src/main/java/com/fepelus/raft/Server.java`)
- Server entrypoint → Raft handler: starts (evidence: `src/main/java/com/fepelus/raft/Server.java`)
- Raft handler → Raft core: drives
- Raft handler → Election timer: uses timer (evidence: `src/main/java/com/fepelus/raft/Handler.java`)
- Raft core → Events: consumes events
- Raft core → Commands: emits commands
- Server entrypoint → Consensus interface: configures (evidence: `src/main/java/com/fepelus/raft/Server.java`)
- Server entrypoint → Network transport: configures (evidence: `src/main/java/com/fepelus/raft/Server.java`)
- Server entrypoint → Network listener: configures (evidence: `src/main/java/com/fepelus/raft/Server.java`)
- Server entrypoint → SQLite state: configures (evidence: `src/main/java/com/fepelus/raft/Server.java`)
- Network transport → Raft peers: exchanges messages
- SQLite state → SQLite: persists state
- Network transport → JeroMQ: uses messaging
- CLI client → Document and nodes: parses KDL (evidence: `src/main/java/com/fepelus/raft/Client.java`)
- CLI client → Document search: queries nodes (evidence: `src/main/java/com/fepelus/raft/Client.java`)
- KDL config files → Configuration: configures
- Parser facade → KDL parser: delegates parsing (evidence: `src/main/java/kdl/parse/KDLParserFacade.java`)
- KDL parser → Parse context: reads input (evidence: `src/main/java/kdl/parse/KDLParser.java`)
- KDL parser → Character rules: checks characters (evidence: `src/main/java/kdl/parse/KDLParser.java`)
- KDL parser → Document and nodes: builds document (evidence: `src/main/java/kdl/parse/KDLParser.java`)
- Document and nodes → Node structure: contains nodes (evidence: `src/main/java/kdl/objects/KDLDocument.java`)
- Node structure → KDL values: stores values (evidence: `src/main/java/kdl/objects/KDLNode.java`)
- Document and nodes → Print settings: prints with settings (evidence: `src/main/java/kdl/objects/KDLDocument.java`)
- Node structure → KDL printer: writes KDL (evidence: `src/main/java/kdl/objects/KDLNode.java`)
- KDL printer → Print settings: checks escaping (evidence: `src/main/java/kdl/print/PrintUtil.java`)
- Document search → Node predicates: tests nodes (evidence: `src/main/java/kdl/search/GeneralSearch.java`)
- Document search → Tree mutations: applies mutations (evidence: `src/main/java/kdl/search/GeneralSearch.java`)
- Document search → Document and nodes: traverses document (evidence: `src/main/java/kdl/search/GeneralSearch.java`)
- Pathed search → Node predicates: tests nodes (evidence: `src/main/java/kdl/search/PathedSearch.java`)
- Root search → Tree mutations: applies mutations (evidence: `src/main/java/kdl/search/RootSearch.java`)
