# routerarchitects/tip-olg-nats-agent-core architecture

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

- Interactive diagram: https://gitdiagram.com/routerarchitects/tip-olg-nats-agent-core
- Repository: https://github.com/routerarchitects/tip-olg-nats-agent-core

## Overview

olg-nats-agent-core is a reusable NATS messaging and desired-state library embedded in long-running agents, not a daemon. An agent submits configure or action commands: configure persists desired state before publishing a notification, while action publishes directly. The target agent receives typed messages, loads or watches desired state as needed, and can publish results or status; subscriptions are restored after reconnect. The graph reflects README capabilities and sampled implementation paths; unsampled APIs are represented only where their directory or path is supported.

Main entry points: [`agentcore/client.go`](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/client.go) (Client facade), [`internal/session/session.go`](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/session/session.go) (Session manager), [`agentcore/handlers_runtime.go`](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/handlers_runtime.go) (Handler runtime), [`internal/transport/publisher.go`](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/transport/publisher.go) (NATS publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Agent API"]
  node_client["Client facade<br/>[client.go]"]
  node_contracts["Message contracts<br/>[contracts.go]"]
end

subgraph group_messaging["Message Routing"]
  node_handlers["Handler runtime"]
  node_subjects["Subject builder<br/>[subjects.go]"]
  node_registry[("Subscription registry<br/>[registry.go]")]
  node_publisher["NATS publisher<br/>[publisher.go]"]
end

subgraph group_state["Desired State"]
  node_kvstore["Desired-config store<br/>[store.go]"]
  node_kvwatch["Desired-config watch<br/>[watch.go]"]
end

subgraph group_runtime["Runtime Session"]
  node_session["Session manager<br/>[session.go]"]
  node_sessionopts["Session defaults<br/>[options.go]"]
end

node_agent(("Owning agent"))
node_nats(("NATS server"))
node_jetstream[("JetStream KV")]

node_agent -->|"calls APIs"| node_client
node_client -->|"validates messages"| node_contracts
node_client -->|"builds subjects"| node_subjects
node_client -->|"starts session"| node_session
node_client -->|"stores and loads"| node_kvstore
node_client -->|"starts watches"| node_kvwatch
node_client -->|"publishes messages"| node_publisher
node_client -->|"registers handlers"| node_handlers
node_handlers -->|"records intent"| node_registry
node_handlers -->|"subscribes and receives"| node_nats
node_handlers -->|"decodes messages"| node_contracts
node_session -->|"normalizes config"| node_sessionopts
node_session -->|"connects"| node_nats
node_session -->|"creates KV access"| node_jetstream
node_publisher -->|"gets connection"| node_session
node_publisher -->|"publishes and flushes"| node_nats
node_kvstore -->|"gets KV handle"| node_session
node_kvwatch -->|"gets KV handle"| node_session
node_kvstore -->|"reads and writes"| node_jetstream
node_kvwatch -->|"watches keys"| node_jetstream
node_nats -->|"delivers messages"| node_handlers
node_handlers -->|"dispatches callbacks"| node_agent
node_agent -->|"registers callbacks"| node_client

click node_client "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/client.go"
click node_contracts "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/contracts.go"
click node_handlers "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/handlers_runtime.go"
click node_subjects "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/subjects/subjects.go"
click node_registry "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/registry/registry.go"
click node_publisher "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/transport/publisher.go"
click node_session "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/session/session.go"
click node_sessionopts "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/session/options.go"
click node_kvstore "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/kv/store.go"
click node_kvwatch "https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/kv/watch.go"

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_contracts toneBlue
class node_handlers,node_subjects,node_registry,node_publisher,node_jetstream toneAmber
class node_kvstore,node_kvwatch,node_nats toneMint
class node_session,node_sessionopts toneRose
class node_agent toneIndigo
```

## Components

### Agent API

- [Client facade](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/client.go): `agentcore/client.go`
- [Message contracts](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/contracts.go): `agentcore/contracts.go`

### Message Routing

- [Handler runtime](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/agentcore/handlers_runtime.go): `agentcore/handlers_runtime.go`
- [Subject builder](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/subjects/subjects.go): `internal/subjects/subjects.go`
- [Subscription registry](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/registry/registry.go): `internal/registry/registry.go`
- [NATS publisher](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/transport/publisher.go): `internal/transport/publisher.go`

### Desired State

- [Desired-config store](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/kv/store.go): `internal/kv/store.go`
- [Desired-config watch](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/kv/watch.go): `internal/kv/watch.go`

### Runtime Session

- [Session manager](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/session/session.go): `internal/session/session.go`
- [Session defaults](https://github.com/routerarchitects/tip-olg-nats-agent-core/blob/main/internal/session/options.go): `internal/session/options.go`

### Other components

- **Owning agent**
- **NATS server**
- **JetStream KV**

## Connections

- Owning agent → Client facade: calls APIs
- Client facade → Message contracts: validates messages
- Client facade → Subject builder: builds subjects
- Client facade → Session manager: starts session
- Client facade → Desired-config store: stores and loads
- Client facade → Desired-config watch: starts watches
- Client facade → NATS publisher: publishes messages
- Client facade → Handler runtime: registers handlers
- Handler runtime → Subscription registry: records intent
- Handler runtime → NATS server: subscribes and receives
- Handler runtime → Message contracts: decodes messages
- Session manager → Session defaults: normalizes config
- Session manager → NATS server: connects
- Session manager → JetStream KV: creates KV access
- NATS publisher → Session manager: gets connection
- NATS publisher → NATS server: publishes and flushes
- Desired-config store → Session manager: gets KV handle
- Desired-config watch → Session manager: gets KV handle
- Desired-config store → JetStream KV: reads and writes
- Desired-config watch → JetStream KV: watches keys
- NATS server → Handler runtime: delivers messages
- Handler runtime → Owning agent: dispatches callbacks
- Owning agent → Client facade: registers callbacks