# itsk4tune/gatekeeper architecture

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

- Interactive diagram: https://gitdiagram.com/itsk4tune/gatekeeper
- Repository: https://github.com/itsk4tune/gatekeeper

## Overview

GateKeeper is an in-memory key-value, rate-limiting, quota, and idempotency server with GKWP/TCP and HTTP interfaces. Clients send requests through the dual-protocol listener to protocol-specific processing and domain operations backed by shared memory storage; optional AOF supports replay and persistence. The README documents the major features and protocols, while excerpts show server wiring and selected HTTP, storage, and idempotency behavior. Several internal TCP and domain call paths are not sampled, so uncertain links are omitted or marked unverified.

Main entry points: [`src/server_main.cpp`](https://github.com/itsk4tune/gatekeeper/blob/main/src/server_main.cpp) (Server Bootstrap), [`src/command/dispatcher.cpp`](https://github.com/itsk4tune/gatekeeper/blob/main/src/command/dispatcher.cpp) (Command Dispatcher), [`src/net/server.cpp`](https://github.com/itsk4tune/gatekeeper/blob/main/src/net/server.cpp) (Dual-Protocol Server), [`src/service/http_service.cpp`](https://github.com/itsk4tune/gatekeeper/blob/main/src/service/http_service.cpp) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and CLI"]
  node_sdk["Client SDKs"]
  node_cli["Server CLI<br/>[app.cpp]"]
end

subgraph group_runtime["Server Runtime"]
  node_main["Server Bootstrap<br/>[server_main.cpp]"]
  node_config["Server Config<br/>[server_config.cpp]"]
  node_logger["Logging<br/>[logger.h]"]
  node_server["Dual-Protocol Server<br/>[server.cpp]"]
  node_eventloop["Event Loop<br/>[event_loop.h]"]
end

subgraph group_protocol["Protocols and Services"]
  node_tcpchannel["TCP Channel<br/>[channel.cpp]"]
  node_gkwp["GKWP Codec<br/>[binary_codec.h]"]
  node_streams["Stream Manager<br/>[stream_manager.cpp]"]
  node_httpchannel["HTTP Channel<br/>[http_channel.h]"]
  node_httpservice["HTTP API<br/>[http_service.cpp]"]
  node_processor["TCP Processor<br/>[processor.cpp]"]
  node_json["JSON Reader<br/>[json_reader.cpp]"]
end

subgraph group_domain["Domain Operations"]
  node_dispatcher["Command Dispatcher<br/>[dispatcher.cpp]"]
  node_kv["Key-Value and TTL"]
  node_ratelimit["Rate Limiting<br/>[counter_ops.cpp]"]
  node_quota["Quota Reservations"]
  node_idempotency["Idempotency"]
  node_parking["Connection Parking<br/>[parking_lot.cpp]"]
end

subgraph group_storage["Storage and Persistence"]
  node_store[("Memory Store<br/>[memory_store.cpp]")]
  node_aofwriter["AOF Writer<br/>[aof_writer.cpp]"]
  node_aofloader["AOF Recovery<br/>[aof_loader.cpp]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_main -->|"parses settings"| node_config
node_main -->|"creates logger"| node_logger
node_main -->|"creates dispatcher"| node_dispatcher
node_main -->|"routes TCP requests"| node_processor
node_main -->|"routes HTTP requests"| node_httpservice
node_main -->|"starts listener"| node_server
node_main -->|"replays log"| node_aofloader
node_main -->|"configures persistence"| node_aofwriter
node_server -->|"runs loops"| node_eventloop
node_server -->|"accepts TCP"| node_tcpchannel
node_server -->|"accepts HTTP"| node_httpchannel
node_tcpchannel -.->|"dispatches payload"| node_processor
node_processor -.->|"dispatches commands"| node_dispatcher
node_httpchannel -.->|"routes requests"| node_httpservice
node_httpservice -->|"parses bodies"| node_json
node_dispatcher -->|"executes operations"| node_store
node_httpservice -->|"reads and writes"| node_store
node_httpservice -->|"appends mutations"| node_aofwriter
node_dispatcher -->|"registers operations"| node_kv
node_dispatcher -->|"registers operations"| node_ratelimit
node_dispatcher -->|"registers operations"| node_quota
node_dispatcher -->|"registers operations"| node_idempotency
node_idempotency -.->|"parks duplicates"| node_parking
node_sdk -.->|"connects to"| node_server
node_gkwp -.->|"multiplexes streams"| node_streams
node_aofloader -->|"replays commands"| node_dispatcher

click node_sdk "https://github.com/itsk4tune/gatekeeper/tree/main/sdk"
click node_cli "https://github.com/itsk4tune/gatekeeper/blob/main/src/cli/app.cpp"
click node_main "https://github.com/itsk4tune/gatekeeper/blob/main/src/server_main.cpp"
click node_config "https://github.com/itsk4tune/gatekeeper/blob/main/src/core/config/server_config.cpp"
click node_logger "https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/core/log/logger.h"
click node_server "https://github.com/itsk4tune/gatekeeper/blob/main/src/net/server.cpp"
click node_eventloop "https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/net/event_loop.h"
click node_tcpchannel "https://github.com/itsk4tune/gatekeeper/blob/main/src/net/channel.cpp"
click node_gkwp "https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/protocol/gkwp2/binary_codec.h"
click node_streams "https://github.com/itsk4tune/gatekeeper/blob/main/src/protocol/gkwp2/stream_manager.cpp"
click node_httpchannel "https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/protocol/http/http_channel.h"
click node_httpservice "https://github.com/itsk4tune/gatekeeper/blob/main/src/service/http_service.cpp"
click node_processor "https://github.com/itsk4tune/gatekeeper/blob/main/src/service/processor.cpp"
click node_json "https://github.com/itsk4tune/gatekeeper/blob/main/src/protocol/json_reader.cpp"
click node_dispatcher "https://github.com/itsk4tune/gatekeeper/blob/main/src/command/dispatcher.cpp"
click node_kv "https://github.com/itsk4tune/gatekeeper/tree/main/src/domain/kv"
click node_ratelimit "https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/ratelimit/counter_ops.cpp"
click node_quota "https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/quota/reservation_ops.cpp"
click node_idempotency "https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/idempotency/idempotency_ops.cpp"
click node_parking "https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/idempotency/parking_lot.cpp"
click node_store "https://github.com/itsk4tune/gatekeeper/blob/main/src/storage/memory_store.cpp"
click node_aofwriter "https://github.com/itsk4tune/gatekeeper/blob/main/src/storage/aof/aof_writer.cpp"
click node_aofloader "https://github.com/itsk4tune/gatekeeper/blob/main/src/storage/aof/aof_loader.cpp"

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_sdk,node_cli toneBlue
class node_main,node_config,node_logger,node_server,node_eventloop toneAmber
class node_tcpchannel,node_gkwp,node_streams,node_httpchannel,node_httpservice,node_processor,node_json toneMint
class node_dispatcher,node_kv,node_ratelimit,node_quota,node_idempotency,node_parking toneRose
class node_store,node_aofwriter,node_aofloader,node_operator toneIndigo
```

## Components

### Clients and CLI

- [Client SDKs](https://github.com/itsk4tune/gatekeeper/tree/main/sdk): `sdk`
- [Server CLI](https://github.com/itsk4tune/gatekeeper/blob/main/src/cli/app.cpp): `src/cli/app.cpp`

### Server Runtime

- [Server Bootstrap](https://github.com/itsk4tune/gatekeeper/blob/main/src/server_main.cpp): `src/server_main.cpp`
- [Server Config](https://github.com/itsk4tune/gatekeeper/blob/main/src/core/config/server_config.cpp): `src/core/config/server_config.cpp`
- [Logging](https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/core/log/logger.h): `include/gatekeeper/core/log/logger.h`
- [Dual-Protocol Server](https://github.com/itsk4tune/gatekeeper/blob/main/src/net/server.cpp): `src/net/server.cpp`
- [Event Loop](https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/net/event_loop.h): `include/gatekeeper/net/event_loop.h`

### Protocols and Services

- [TCP Channel](https://github.com/itsk4tune/gatekeeper/blob/main/src/net/channel.cpp): `src/net/channel.cpp`
- [GKWP Codec](https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/protocol/gkwp2/binary_codec.h): `include/gatekeeper/protocol/gkwp2/binary_codec.h`
- [Stream Manager](https://github.com/itsk4tune/gatekeeper/blob/main/src/protocol/gkwp2/stream_manager.cpp): `src/protocol/gkwp2/stream_manager.cpp`
- [HTTP Channel](https://github.com/itsk4tune/gatekeeper/blob/main/include/gatekeeper/protocol/http/http_channel.h): `include/gatekeeper/protocol/http/http_channel.h`
- [HTTP API](https://github.com/itsk4tune/gatekeeper/blob/main/src/service/http_service.cpp): `src/service/http_service.cpp`
- [TCP Processor](https://github.com/itsk4tune/gatekeeper/blob/main/src/service/processor.cpp): `src/service/processor.cpp`
- [JSON Reader](https://github.com/itsk4tune/gatekeeper/blob/main/src/protocol/json_reader.cpp): `src/protocol/json_reader.cpp`

### Domain Operations

- [Command Dispatcher](https://github.com/itsk4tune/gatekeeper/blob/main/src/command/dispatcher.cpp): `src/command/dispatcher.cpp`
- [Key-Value and TTL](https://github.com/itsk4tune/gatekeeper/tree/main/src/domain/kv): `src/domain/kv`
- [Rate Limiting](https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/ratelimit/counter_ops.cpp): `src/domain/ratelimit/counter_ops.cpp`
- [Quota Reservations](https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/quota/reservation_ops.cpp): `src/domain/quota/reservation_ops.cpp`
- [Idempotency](https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/idempotency/idempotency_ops.cpp): `src/domain/idempotency/idempotency_ops.cpp`
- [Connection Parking](https://github.com/itsk4tune/gatekeeper/blob/main/src/domain/idempotency/parking_lot.cpp): `src/domain/idempotency/parking_lot.cpp`

### Storage and Persistence

- [Memory Store](https://github.com/itsk4tune/gatekeeper/blob/main/src/storage/memory_store.cpp): `src/storage/memory_store.cpp`
- [AOF Writer](https://github.com/itsk4tune/gatekeeper/blob/main/src/storage/aof/aof_writer.cpp): `src/storage/aof/aof_writer.cpp`
- [AOF Recovery](https://github.com/itsk4tune/gatekeeper/blob/main/src/storage/aof/aof_loader.cpp): `src/storage/aof/aof_loader.cpp`

### Other components

- **Operator**

## Connections

- Operator → Server CLI: runs commands (evidence: `src/cli/app.cpp`)
- Server Bootstrap → Server Config: parses settings (evidence: `src/server_main.cpp`)
- Server Bootstrap → Logging: creates logger (evidence: `src/server_main.cpp`)
- Server Bootstrap → Command Dispatcher: creates dispatcher (evidence: `src/server_main.cpp`)
- Server Bootstrap → TCP Processor: routes TCP requests (evidence: `src/server_main.cpp`)
- Server Bootstrap → HTTP API: routes HTTP requests (evidence: `src/server_main.cpp`)
- Server Bootstrap → Dual-Protocol Server: starts listener (evidence: `src/server_main.cpp`)
- Server Bootstrap → AOF Recovery: replays log (evidence: `src/server_main.cpp`)
- Server Bootstrap → AOF Writer: configures persistence (evidence: `src/server_main.cpp`)
- Dual-Protocol Server → Event Loop: runs loops
- Dual-Protocol Server → TCP Channel: accepts TCP (evidence: `src/net/server.cpp`)
- Dual-Protocol Server → HTTP Channel: accepts HTTP (evidence: `src/net/server.cpp`)
- TCP Channel → TCP Processor: dispatches payload
- TCP Processor → Command Dispatcher: dispatches commands
- HTTP Channel → HTTP API: routes requests
- HTTP API → JSON Reader: parses bodies (evidence: `src/service/http_service.cpp`)
- Command Dispatcher → Memory Store: executes operations
- HTTP API → Memory Store: reads and writes (evidence: `src/service/http_service.cpp`)
- HTTP API → AOF Writer: appends mutations (evidence: `src/service/http_service.cpp`)
- Command Dispatcher → Key-Value and TTL: registers operations (evidence: `src/command/dispatcher.cpp`)
- Command Dispatcher → Rate Limiting: registers operations (evidence: `src/command/dispatcher.cpp`)
- Command Dispatcher → Quota Reservations: registers operations (evidence: `src/command/dispatcher.cpp`)
- Command Dispatcher → Idempotency: registers operations (evidence: `src/command/dispatcher.cpp`)
- Idempotency → Connection Parking: parks duplicates
- Client SDKs → Dual-Protocol Server: connects to
- GKWP Codec → Stream Manager: multiplexes streams
- AOF Recovery → Command Dispatcher: replays commands
