# kgcorner/aquila architecture

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

- Interactive diagram: https://gitdiagram.com/kgcorner/aquila
- Repository: https://github.com/kgcorner/aquila

## Overview

Aquila is an in-memory distributed cache with a balancer/receptionist front end and main/backup storage nodes. The client workflow accepts GET, SET, PUT, and DEL requests, routes them through key-to-node metadata, and returns node results; INFO reports node counts. Main nodes replicate writes and deletes to configured backups. The graph reflects the sampled request and node code; load balancing, node lifecycle, and health monitoring are included from the repository structure and documented class responsibilities, but their unsampled wiring is not inferred.

Main entry points: [`balancer/src/main/java/com/kgaurav/balancer/Receptionist.java`](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/Receptionist.java) (Receptionist), [`node/src/main/java/com/kgaurav/kmem/Server.java`](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Server.java) (Node Server), [`balancer/src/main/java/com/kgaurav/balancer/BalancerServer.java`](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/BalancerServer.java) (Balancer Server), [`node/src/main/java/com/kgaurav/kmem/Util.java`](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Util.java) (Node Network I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Client Interface"]
  node_receptionist["Receptionist<br/>[Receptionist.java]"]
  node_request["Request Protocol<br/>[Request.java]"]
  node_response["Response Protocol<br/>[Response.java]"]
  node_client_util["Balancer Network I/O<br/>[Util.java]"]
end

subgraph group_routing["Balancing And Routing"]
  node_balancer_app["Balancer Startup<br/>[Application.java]"]
  node_balancer_server["Balancer Server"]
  node_key_store[("Key Routing<br/>[KeyStore.java]")]
  node_node_meta["Node Metadata<br/>[Node.java]"]
end

subgraph group_storage["Node Storage"]
  node_node_app["Node Startup<br/>[Application.java]"]
  node_node_server["Node Server<br/>[Server.java]"]
  node_item["Stored Item<br/>[Item.java]"]
  node_store[("Memory Store<br/>[Store.java]")]
  node_node_protocol["Node Commands<br/>[Command.java]"]
  node_node_util["Node Network I/O<br/>[Util.java]"]
end

subgraph group_replication["Replication And Health"]
  node_sync[("Backup Registry<br/>[SyncSystem.java]")]
  node_stethoscope["Node Monitor<br/>[Stethoscope.java]"]
end

node_client(("Cache Client"))

node_client -->|"sends requests"| node_receptionist
node_receptionist -->|"parses"| node_request
node_receptionist -->|"routes keys"| node_key_store
node_receptionist -->|"selects node"| node_balancer_server
node_receptionist -->|"forwards commands"| node_client_util
node_client_util -->|"sends commands"| node_node_server
node_node_server -->|"decodes commands"| node_node_protocol
node_node_server -->|"reads or mutates"| node_store
node_store -->|"stores items"| node_item
node_node_server -->|"returns results"| node_node_util
node_node_util -->|"returns responses"| node_receptionist
node_receptionist -->|"forms client result"| node_response
node_response -->|"returns result"| node_client
node_balancer_app -->|"starts server"| node_balancer_server
node_balancer_app -->|"deploys listener"| node_receptionist
node_balancer_server -->|"starts nodes"| node_node_app
node_node_app -->|"starts listener"| node_node_server
node_node_server -->|"registers node"| node_node_util
node_node_util -->|"sends registration"| node_balancer_server
node_balancer_server -->|"tracks nodes"| node_node_meta
node_receptionist -->|"assigns key metadata"| node_key_store
node_node_server -->|"reads backups"| node_sync
node_node_server -.->|"sends replicated writes"| node_node_util
node_sync -->|"lists backup targets"| node_node_meta
node_stethoscope -.->|"updates node set"| node_sync

click node_receptionist "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/Receptionist.java"
click node_request "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/model/Request.java"
click node_response "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/model/Response.java"
click node_balancer_app "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/Application.java"
click node_balancer_server "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/BalancerServer.java"
click node_key_store "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/KeyStore.java"
click node_node_meta "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/model/Node.java"
click node_node_app "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Application.java"
click node_node_server "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Server.java"
click node_item "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/model/Item.java"
click node_store "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/data/Store.java"
click node_node_protocol "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/model/Command.java"
click node_sync "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/data/SyncSystem.java"
click node_stethoscope "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Stethoscope.java"
click node_client_util "https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/util/Util.java"
click node_node_util "https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Util.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_receptionist,node_request,node_response,node_client_util toneBlue
class node_balancer_app,node_balancer_server,node_key_store,node_node_meta,node_client toneAmber
class node_node_app,node_node_server,node_item,node_store,node_node_protocol,node_node_util toneMint
class node_sync,node_stethoscope toneRose
```

## Components

### Client Interface

- [Receptionist](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/Receptionist.java): `balancer/src/main/java/com/kgaurav/balancer/Receptionist.java`
- [Request Protocol](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/model/Request.java): `balancer/src/main/java/com/kgaurav/balancer/model/Request.java`
- [Response Protocol](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/model/Response.java): `balancer/src/main/java/com/kgaurav/balancer/model/Response.java`
- [Balancer Network I/O](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/util/Util.java): `balancer/src/main/java/com/kgaurav/balancer/util/Util.java`

### Balancing And Routing

- [Balancer Startup](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/Application.java): `balancer/src/main/java/com/kgaurav/balancer/Application.java`
- [Balancer Server](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/BalancerServer.java): `balancer/src/main/java/com/kgaurav/balancer/BalancerServer.java`
- [Key Routing](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/KeyStore.java): `balancer/src/main/java/com/kgaurav/balancer/KeyStore.java`
- [Node Metadata](https://github.com/kgcorner/aquila/blob/master/balancer/src/main/java/com/kgaurav/balancer/model/Node.java): `balancer/src/main/java/com/kgaurav/balancer/model/Node.java`

### Node Storage

- [Node Startup](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Application.java): `node/src/main/java/com/kgaurav/kmem/Application.java`
- [Node Server](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Server.java): `node/src/main/java/com/kgaurav/kmem/Server.java`
- [Stored Item](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/model/Item.java): `node/src/main/java/com/kgaurav/kmem/model/Item.java`
- [Memory Store](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/data/Store.java): `node/src/main/java/com/kgaurav/kmem/data/Store.java`
- [Node Commands](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/model/Command.java): `node/src/main/java/com/kgaurav/kmem/model/Command.java`
- [Node Network I/O](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Util.java): `node/src/main/java/com/kgaurav/kmem/Util.java`

### Replication And Health

- [Backup Registry](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/data/SyncSystem.java): `node/src/main/java/com/kgaurav/kmem/data/SyncSystem.java`
- [Node Monitor](https://github.com/kgcorner/aquila/blob/master/node/src/main/java/com/kgaurav/kmem/Stethoscope.java): `node/src/main/java/com/kgaurav/kmem/Stethoscope.java`

### Other components

- **Cache Client**

## Connections

- Cache Client → Receptionist: sends requests
- Receptionist → Request Protocol: parses
- Receptionist → Key Routing: routes keys
- Receptionist → Balancer Server: selects node
- Receptionist → Balancer Network I/O: forwards commands
- Balancer Network I/O → Node Server: sends commands
- Node Server → Node Commands: decodes commands
- Node Server → Memory Store: reads or mutates
- Memory Store → Stored Item: stores items
- Node Server → Node Network I/O: returns results
- Node Network I/O → Receptionist: returns responses
- Receptionist → Response Protocol: forms client result
- Response Protocol → Cache Client: returns result
- Balancer Startup → Balancer Server: starts server
- Balancer Startup → Receptionist: deploys listener
- Balancer Server → Node Startup: starts nodes
- Node Startup → Node Server: starts listener
- Node Server → Node Network I/O: registers node
- Node Network I/O → Balancer Server: sends registration
- Balancer Server → Node Metadata: tracks nodes
- Receptionist → Key Routing: assigns key metadata
- Node Server → Backup Registry: reads backups
- Node Server → Node Network I/O: sends replicated writes
- Backup Registry → Node Metadata: lists backup targets
- Node Monitor → Backup Registry: updates node set