# stoufexis/jarpc architecture

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

- Interactive diagram: https://gitdiagram.com/stoufexis/jarpc
- Repository: https://github.com/stoufexis/jarpc

## Overview

Jarpc is a schema-driven Java RPC generator plus a runtime built on Aeron. The main workflow is: a caller supplies a service specification, the generator parses RPC fields and types and renders typed client/server and codec classes; generated clients encode and publish requests, while generated servers decode requests and encode responses. Runtime support handles Aeron connections, message framing, polling, and concurrent-client dispatch. The README documents both client modes and the single-threaded server. Runtime internals are sampled selectively, so unsampled links are omitted rather than inferred.

Main entry points: [`lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java`](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java) (Server transport), [`generator/src/main/resources/template`](https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template) (Typed RPC classes), [`lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java`](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java) (Single-thread client base), [`generator/src/main/resources/template/client/ConcurrentJarpcClient.java`](https://github.com/stoufexis/jarpc/blob/main/generator/src/main/resources/template/client/ConcurrentJarpcClient.java) (Concurrent client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Schema generation"]
  node_cli["Generator CLI<br/>[Cli.java]"]
  node_schema["Schema model<br/>[Spec.java]"]
  node_generator["Template generator<br/>[Generator.java]"]
  node_generated["Typed RPC classes"]
end

subgraph group_client["Client runtime"]
  node_genclient["Generated clients"]
  node_concurrent["Concurrent client"]
  node_singleclient["Single-thread client base"]
  node_callback["Response dispatch"]
  node_ringbuffer["Request queue"]
  node_error["Client error handling"]
end

subgraph group_protocol["Protocol support"]
  node_wiretemplates["Generated codecs"]
  node_config["Connection config"]
  node_publisher["Message publisher<br/>[Publisher.java]"]
  node_header["Message framing"]
  node_encode["Field encoding<br/>[EncodeUtil.java]"]
  node_decode["Field decoding<br/>[DecodeUtil.java]"]
end

subgraph group_server["Server runtime"]
  node_genserver["Generated server"]
  node_server["Server transport"]
  node_state["Server state machine"]
  node_images["Client image tracking<br/>[Images.java]"]
  node_publications["Server publications"]
end

node_developer(("Service developer"))
node_spec["RPC specification"]
node_aeron["Aeron transport"]

node_developer -->|"defines schema"| node_spec
node_developer -->|"runs generator"| node_cli
node_cli -->|"parses spec"| node_schema
node_cli -->|"requests generation"| node_generator
node_generator -->|"renders from"| node_schema
node_generator -->|"renders templates"| node_generated
node_generated -->|"includes"| node_genclient
node_generated -->|"includes"| node_genserver
node_generated -->|"includes"| node_wiretemplates
node_concurrent -->|"delegates polling"| node_singleclient
node_concurrent -->|"queues requests"| node_ringbuffer
node_concurrent -->|"dispatches responses"| node_callback
node_singleclient -->|"publishes requests"| node_publisher
node_singleclient -->|"decodes headers"| node_header
node_singleclient -->|"reports errors"| node_error
node_genclient -->|"encodes fields"| node_encode
node_genclient -->|"decodes fields"| node_decode
node_config -->|"configures connections"| node_aeron
node_publisher -->|"writes headers"| node_header
node_genserver -->|"encodes responses"| node_encode
node_genserver -->|"decodes requests"| node_decode
node_server -->|"drives state"| node_state
node_server -->|"tracks images"| node_images
node_server -->|"uses publications"| node_publications
node_server -->|"decodes headers"| node_header
node_server -.->|"receives messages"| node_aeron

click node_cli "https://github.com/stoufexis/jarpc/blob/main/generator/src/main/java/stoufexis/jarpc/gen/Cli.java"
click node_schema "https://github.com/stoufexis/jarpc/blob/main/generator/src/main/java/stoufexis/jarpc/gen/model/Spec.java"
click node_generator "https://github.com/stoufexis/jarpc/blob/main/generator/src/main/java/stoufexis/jarpc/gen/Generator.java"
click node_generated "https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template"
click node_genclient "https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template/client"
click node_genserver "https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template/server"
click node_wiretemplates "https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template/common"
click node_concurrent "https://github.com/stoufexis/jarpc/blob/main/generator/src/main/resources/template/client/ConcurrentJarpcClient.java"
click node_singleclient "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java"
click node_callback "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/concurrent/ResponseHandlerUtil.java"
click node_ringbuffer "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/ringbuffer/MPSCBufferPollAgent.java"
click node_error "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/ClientErrorHandler.java"
click node_config "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/ConnectionConfig.java"
click node_publisher "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/Publisher.java"
click node_header "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/internal/MessageHeaderCodec.java"
click node_encode "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/EncodeUtil.java"
click node_decode "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/DecodeUtil.java"
click node_server "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java"
click node_state "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/ServerStateMachine.java"
click node_images "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/Images.java"
click node_publications "https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/internal/ServerPublications.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_cli,node_schema,node_generator,node_generated toneBlue
class node_genclient,node_concurrent,node_singleclient,node_callback,node_ringbuffer,node_error toneAmber
class node_wiretemplates,node_config,node_publisher,node_header,node_encode,node_decode toneMint
class node_genserver,node_server,node_state,node_images,node_publications toneRose
class node_developer,node_spec,node_aeron toneIndigo
```

## Components

### Schema generation

- [Generator CLI](https://github.com/stoufexis/jarpc/blob/main/generator/src/main/java/stoufexis/jarpc/gen/Cli.java): `generator/src/main/java/stoufexis/jarpc/gen/Cli.java`
- [Schema model](https://github.com/stoufexis/jarpc/blob/main/generator/src/main/java/stoufexis/jarpc/gen/model/Spec.java): `generator/src/main/java/stoufexis/jarpc/gen/model/Spec.java`
- [Template generator](https://github.com/stoufexis/jarpc/blob/main/generator/src/main/java/stoufexis/jarpc/gen/Generator.java): `generator/src/main/java/stoufexis/jarpc/gen/Generator.java`
- [Typed RPC classes](https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template): `generator/src/main/resources/template`

### Client runtime

- [Generated clients](https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template/client): `generator/src/main/resources/template/client`
- [Concurrent client](https://github.com/stoufexis/jarpc/blob/main/generator/src/main/resources/template/client/ConcurrentJarpcClient.java): `generator/src/main/resources/template/client/ConcurrentJarpcClient.java`
- [Single-thread client base](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java): `lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java`
- [Response dispatch](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/concurrent/ResponseHandlerUtil.java): `lib/src/main/java/stoufexis/jarpc/lib/client/concurrent/ResponseHandlerUtil.java`
- [Request queue](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/ringbuffer/MPSCBufferPollAgent.java): `lib/src/main/java/stoufexis/jarpc/lib/client/ringbuffer/MPSCBufferPollAgent.java`
- [Client error handling](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/client/ClientErrorHandler.java): `lib/src/main/java/stoufexis/jarpc/lib/client/ClientErrorHandler.java`

### Protocol support

- [Generated codecs](https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template/common): `generator/src/main/resources/template/common`
- [Connection config](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/ConnectionConfig.java): `lib/src/main/java/stoufexis/jarpc/lib/common/ConnectionConfig.java`
- [Message publisher](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/Publisher.java): `lib/src/main/java/stoufexis/jarpc/lib/common/Publisher.java`
- [Message framing](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/internal/MessageHeaderCodec.java): `lib/src/main/java/stoufexis/jarpc/lib/common/internal/MessageHeaderCodec.java`
- [Field encoding](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/EncodeUtil.java): `lib/src/main/java/stoufexis/jarpc/lib/common/EncodeUtil.java`
- [Field decoding](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/common/DecodeUtil.java): `lib/src/main/java/stoufexis/jarpc/lib/common/DecodeUtil.java`

### Server runtime

- [Generated server](https://github.com/stoufexis/jarpc/tree/main/generator/src/main/resources/template/server): `generator/src/main/resources/template/server`
- [Server transport](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java): `lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java`
- [Server state machine](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/ServerStateMachine.java): `lib/src/main/java/stoufexis/jarpc/lib/server/ServerStateMachine.java`
- [Client image tracking](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/Images.java): `lib/src/main/java/stoufexis/jarpc/lib/server/Images.java`
- [Server publications](https://github.com/stoufexis/jarpc/blob/main/lib/src/main/java/stoufexis/jarpc/lib/server/internal/ServerPublications.java): `lib/src/main/java/stoufexis/jarpc/lib/server/internal/ServerPublications.java`

### Other components

- **Service developer**
- **RPC specification**
- **Aeron transport**

## Connections

- Service developer → RPC specification: defines schema (evidence: `README.md`)
- Service developer → Generator CLI: runs generator (evidence: `README.md`)
- Generator CLI → Schema model: parses spec (evidence: `generator/src/main/java/stoufexis/jarpc/gen/Cli.java`)
- Generator CLI → Template generator: requests generation (evidence: `generator/src/main/java/stoufexis/jarpc/gen/Cli.java`)
- Template generator → Schema model: renders from (evidence: `generator/src/main/java/stoufexis/jarpc/gen/Generator.java`)
- Template generator → Typed RPC classes: renders templates (evidence: `generator/src/main/java/stoufexis/jarpc/gen/Generator.java`)
- Typed RPC classes → Generated clients: includes (evidence: `README.md`)
- Typed RPC classes → Generated server: includes (evidence: `README.md`)
- Typed RPC classes → Generated codecs: includes (evidence: `README.md`)
- Concurrent client → Single-thread client base: delegates polling (evidence: `generator/src/main/resources/template/client/ConcurrentJarpcClient.java`)
- Concurrent client → Request queue: queues requests (evidence: `generator/src/main/resources/template/client/ConcurrentJarpcClient.java`)
- Concurrent client → Response dispatch: dispatches responses (evidence: `generator/src/main/resources/template/client/ConcurrentJarpcClient.java`)
- Single-thread client base → Message publisher: publishes requests (evidence: `lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java`)
- Single-thread client base → Message framing: decodes headers (evidence: `lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java`)
- Single-thread client base → Client error handling: reports errors (evidence: `lib/src/main/java/stoufexis/jarpc/lib/client/singlethread/SingleThreadedJarpcClient.java`)
- Generated clients → Field encoding: encodes fields (evidence: `generator/src/main/resources/template/client/SingleThreadedJarpcClient.java`)
- Generated clients → Field decoding: decodes fields (evidence: `generator/src/main/resources/template/client/SingleThreadedJarpcClient.java`)
- Connection config → Aeron transport: configures connections
- Message publisher → Message framing: writes headers (evidence: `lib/src/main/java/stoufexis/jarpc/lib/common/Publisher.java`)
- Generated server → Field encoding: encodes responses (evidence: `generator/src/main/resources/template/server/SingleThreadedJarpcServer.java`)
- Generated server → Field decoding: decodes requests (evidence: `generator/src/main/resources/template/server/SingleThreadedJarpcServer.java`)
- Server transport → Server state machine: drives state (evidence: `lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java`)
- Server transport → Client image tracking: tracks images (evidence: `lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java`)
- Server transport → Server publications: uses publications (evidence: `lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java`)
- Server transport → Message framing: decodes headers (evidence: `lib/src/main/java/stoufexis/jarpc/lib/server/SingleThreadedJarpcServer.java`)
- Server transport → Aeron transport: receives messages
