# ktaffy/wren architecture

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

- Interactive diagram: https://gitdiagram.com/ktaffy/wren
- Repository: https://github.com/ktaffy/wren

## Overview

Wren is an RPC framework: a Python client sends method calls over TCP to the C server, which dispatches them to registered handlers and returns a response or error. The C runtime also provides typed payload encoding/decoding and per-call handler APIs. The separate wrengen tool parses and validates service schemas for code generation; the available excerpts show its lexer and parser, but not its CLI or generation wiring. The graph omits uncertain connections and reflects only documented or sampled runtime behavior.

Main entry points: [`c/src/server/conn.c`](https://github.com/ktaffy/wren/blob/master/c/src/server/conn.c) (Connection I/O), [`c/src/server/server.c`](https://github.com/ktaffy/wren/blob/master/c/src/server/server.c) (Server loop), [`c/src/server/dispatch.c`](https://github.com/ktaffy/wren/blob/master/c/src/server/dispatch.c) (Call dispatch), [`c/src/server/call.c`](https://github.com/ktaffy/wren/blob/master/c/src/server/call.c) (Handler call API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["C RPC server"]
  node_server["Server loop<br/>[server.c]"]
  node_accept["Connection accept<br/>[accept.c]"]
  node_conn["Connection I/O<br/>[conn.c]"]
  node_dispatch["Call dispatch<br/>[dispatch.c]"]
  node_handlers["Registered handlers<br/>[server.h]"]
  node_call_api["Handler call API<br/>[call.c]"]
  node_protocol["Protocol codecs<br/>[proto.c]"]
end

subgraph group_client["Python client"]
  node_client_api["Client API<br/>[client.py]"]
end

subgraph group_schema["Schema tooling"]
  node_wrengen_cli["Generator CLI<br/>[cli.py]"]
  node_lexer["Schema lexer<br/>[lexer.py]"]
  node_parser["Schema parser<br/>[parser.py]"]
  node_ast["Schema AST<br/>[ast.py]"]
  node_validate["Schema validation<br/>[validate.py]"]
end

node_caller(("RPC caller"))
node_tcp(("TCP connection"))
node_schema_author(("Schema author"))

node_caller -->|"calls"| node_client_api
node_client_api -->|"sends call"| node_tcp
node_tcp -->|"connects"| node_server
node_server -->|"handles readiness"| node_accept
node_accept -->|"creates connection"| node_conn
node_server -->|"handles events"| node_conn
node_conn -->|"decodes header"| node_protocol
node_conn -->|"dispatches call"| node_dispatch
node_dispatch -->|"looks up method"| node_handlers
node_dispatch -->|"invokes handler"| node_call_api
node_call_api -->|"encodes reply"| node_protocol
node_call_api -->|"writes response"| node_conn
node_conn -->|"sends response"| node_tcp
node_schema_author -->|"provides schema"| node_wrengen_cli
node_wrengen_cli -->|"parses input"| node_parser
node_parser -->|"tokenizes via"| node_lexer
node_parser -->|"builds"| node_ast
node_wrengen_cli -->|"validates schema"| node_validate

click node_client_api "https://github.com/ktaffy/wren/blob/master/python/src/wren/client.py"
click node_server "https://github.com/ktaffy/wren/blob/master/c/src/server/server.c"
click node_accept "https://github.com/ktaffy/wren/blob/master/c/src/server/accept.c"
click node_conn "https://github.com/ktaffy/wren/blob/master/c/src/server/conn.c"
click node_dispatch "https://github.com/ktaffy/wren/blob/master/c/src/server/dispatch.c"
click node_handlers "https://github.com/ktaffy/wren/blob/master/c/include/wren/server.h"
click node_call_api "https://github.com/ktaffy/wren/blob/master/c/src/server/call.c"
click node_protocol "https://github.com/ktaffy/wren/blob/master/c/src/proto.c"
click node_wrengen_cli "https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/cli.py"
click node_lexer "https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/lexer.py"
click node_parser "https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/parser.py"
click node_ast "https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/ast.py"
click node_validate "https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/validate.py"

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_server,node_accept,node_conn,node_dispatch,node_handlers,node_call_api,node_protocol toneBlue
class node_client_api toneAmber
class node_wrengen_cli,node_lexer,node_parser,node_ast,node_validate toneMint
class node_caller,node_tcp,node_schema_author toneIndigo
```

## Components

### C RPC server

- [Server loop](https://github.com/ktaffy/wren/blob/master/c/src/server/server.c): `c/src/server/server.c`
- [Connection accept](https://github.com/ktaffy/wren/blob/master/c/src/server/accept.c): `c/src/server/accept.c`
- [Connection I/O](https://github.com/ktaffy/wren/blob/master/c/src/server/conn.c): `c/src/server/conn.c`
- [Call dispatch](https://github.com/ktaffy/wren/blob/master/c/src/server/dispatch.c): `c/src/server/dispatch.c`
- [Registered handlers](https://github.com/ktaffy/wren/blob/master/c/include/wren/server.h): `c/include/wren/server.h`
- [Handler call API](https://github.com/ktaffy/wren/blob/master/c/src/server/call.c): `c/src/server/call.c`
- [Protocol codecs](https://github.com/ktaffy/wren/blob/master/c/src/proto.c): `c/src/proto.c`

### Python client

- [Client API](https://github.com/ktaffy/wren/blob/master/python/src/wren/client.py): `python/src/wren/client.py`

### Schema tooling

- [Generator CLI](https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/cli.py): `wrengen/src/wrengen/cli.py`
- [Schema lexer](https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/lexer.py): `wrengen/src/wrengen/lexer.py`
- [Schema parser](https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/parser.py): `wrengen/src/wrengen/parser.py`
- [Schema AST](https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/ast.py): `wrengen/src/wrengen/ast.py`
- [Schema validation](https://github.com/ktaffy/wren/blob/master/wrengen/src/wrengen/validate.py): `wrengen/src/wrengen/validate.py`

### Other components

- **RPC caller**
- **TCP connection**
- **Schema author**

## Connections

- RPC caller → Client API: calls
- Client API → TCP connection: sends call
- TCP connection → Server loop: connects
- Server loop → Connection accept: handles readiness
- Connection accept → Connection I/O: creates connection
- Server loop → Connection I/O: handles events
- Connection I/O → Protocol codecs: decodes header
- Connection I/O → Call dispatch: dispatches call
- Call dispatch → Registered handlers: looks up method
- Call dispatch → Handler call API: invokes handler
- Handler call API → Protocol codecs: encodes reply
- Handler call API → Connection I/O: writes response
- Connection I/O → TCP connection: sends response
- Schema author → Generator CLI: provides schema
- Generator CLI → Schema parser: parses input
- Schema parser → Schema lexer: tokenizes via
- Schema parser → Schema AST: builds
- Generator CLI → Schema validation: validates schema