# teceer/pipsim architecture

> Architecture diagram of the GitHub repository teceer/pipsim, 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/teceer/pipsim
- Repository: https://github.com/teceer/pipsim
- Video tour (about a minute): https://gitdiagram.com/teceer/pipsim/video

## Overview

Pipsim is a polyglot, event-driven world simulation. The main user workflow is browser join and live-world viewing: the gateway obtains authoritative world state from sim-core, while the browser renders updates and can predict locally with the shared Rust/WASM simulation. Separately, the gateway discovers workplaces and drives hiring and work; the bank books money movements. Broadcast is documented as a fan-out tier, but the README says it is not yet real, so its links reflect only the sampled stream and PubSub behavior. Several peripheral services are contracts or skeletons; uncertain wiring is omitted.

Main entry points: [`services/world-gateway/internal/gateway/gateway.go`](https://github.com/teceer/pipsim/blob/main/services/world-gateway/internal/gateway/gateway.go) (World gateway), [`web/src/main.ts`](https://github.com/teceer/pipsim/blob/main/web/src/main.ts) (Browser client), [`services/world-gateway/internal/economy/driver.go`](https://github.com/teceer/pipsim/blob/main/services/world-gateway/internal/economy/driver.go) (Economy driver), [`services/bank/internal/bankapi/bankapi.go`](https://github.com/teceer/pipsim/blob/main/services/bank/internal/bankapi/bankapi.go) (Bank API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and fan-out"]
  node_browser["Browser client<br/>[main.ts]"]
  node_wasm["WASM predictor<br/>[lib.rs]"]
  node_broadcast["Broadcast service<br/>[application.ex]"]
  node_fanout["Stream fan-out<br/>[gateway_client.ex]"]
  node_channels["World channels<br/>[world_channel.ex]"]
  node_bff["BFF and jobs<br/>[index.ts]"]
end

subgraph group_simulation["Simulation runtime"]
  node_gateway["World gateway<br/>[gateway.go]"]
  node_simserver["Simulation server<br/>[main.rs]"]
  node_simcore["Deterministic core<br/>[lib.rs]"]
end

subgraph group_economy["Work and economy"]
  node_bank["Bank API<br/>[bankapi.go]"]
  node_ledger[("Ledger store<br/>[postgres.go]")]
  node_economydriver["Economy driver<br/>[driver.go]"]
  node_farm["Farm workplace<br/>[farm.go]"]
  node_tavern["Tavern workplace<br/>[workplace.ex]"]
  node_workshop["Workshop workplace"]
end

subgraph group_contracts["Service contracts"]
  node_contracts["Protobuf contracts<br/>[world.proto]"]
end

node_player(("Player"))
node_kafka["Kafka fact log"]
node_rabbit["RabbitMQ offers"]

node_player -->|"uses"| node_browser
node_browser -->|"joins and streams"| node_gateway
node_browser -.->|"predicts locally"| node_wasm
node_gateway -->|"requests world state"| node_simserver
node_simserver -->|"steps world"| node_simcore
node_simserver -->|"publishes facts"| node_kafka
node_gateway -->|"drives economy"| node_economydriver
node_economydriver -->|"calls workplace"| node_farm
node_economydriver -.->|"calls workplace"| node_tavern
node_economydriver -->|"publishes offers"| node_rabbit
node_rabbit -->|"delivers offers"| node_farm
node_rabbit -.->|"delivers offers"| node_tavern
node_gateway -->|"calls bank"| node_bank
node_bank -->|"reads and writes"| node_ledger
node_bank -->|"publishes money facts"| node_kafka
node_kafka -.->|"delivers lifecycle and purchases"| node_bank
node_broadcast -->|"starts client"| node_fanout
node_fanout -.->|"streams world"| node_gateway
node_fanout -->|"publishes deltas"| node_channels
node_browser -.->|"subscribes"| node_channels
node_bff -.->|"schedules jobs"| node_rabbit

click node_browser "https://github.com/teceer/pipsim/blob/main/web/src/main.ts"
click node_wasm "https://github.com/teceer/pipsim/blob/main/services/sim-core/crates/wasm/src/lib.rs"
click node_broadcast "https://github.com/teceer/pipsim/blob/main/services/broadcast/lib/broadcast/application.ex"
click node_fanout "https://github.com/teceer/pipsim/blob/main/services/broadcast/lib/broadcast/gateway_client.ex"
click node_channels "https://github.com/teceer/pipsim/blob/main/services/broadcast/lib/broadcast/world_channel.ex"
click node_gateway "https://github.com/teceer/pipsim/blob/main/services/world-gateway/internal/gateway/gateway.go"
click node_simserver "https://github.com/teceer/pipsim/blob/main/services/sim-core/crates/server/src/main.rs"
click node_simcore "https://github.com/teceer/pipsim/blob/main/services/sim-core/crates/sim/src/lib.rs"
click node_bank "https://github.com/teceer/pipsim/blob/main/services/bank/internal/bankapi/bankapi.go"
click node_ledger "https://github.com/teceer/pipsim/blob/main/services/bank/internal/ledger/postgres.go"
click node_economydriver "https://github.com/teceer/pipsim/blob/main/services/world-gateway/internal/economy/driver.go"
click node_farm "https://github.com/teceer/pipsim/blob/main/services/workplaces/farm/internal/farm/farm.go"
click node_tavern "https://github.com/teceer/pipsim/blob/main/services/workplaces/tavern/lib/tavern/workplace.ex"
click node_workshop "https://github.com/teceer/pipsim/tree/main/services/workplaces/workshop"
click node_bff "https://github.com/teceer/pipsim/blob/main/services/bff/src/index.ts"
click node_contracts "https://github.com/teceer/pipsim/blob/main/proto/pips/world/v1/world.proto"

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_browser,node_wasm,node_broadcast,node_fanout,node_channels,node_bff toneBlue
class node_gateway,node_simserver,node_simcore toneAmber
class node_bank,node_ledger,node_economydriver,node_farm,node_tavern,node_workshop toneMint
class node_contracts toneRose
class node_player,node_kafka,node_rabbit toneIndigo
```

## Components

### Client and fan-out

- [Browser client](https://github.com/teceer/pipsim/blob/main/web/src/main.ts): `web/src/main.ts`
- [WASM predictor](https://github.com/teceer/pipsim/blob/main/services/sim-core/crates/wasm/src/lib.rs): `services/sim-core/crates/wasm/src/lib.rs`
- [Broadcast service](https://github.com/teceer/pipsim/blob/main/services/broadcast/lib/broadcast/application.ex): `services/broadcast/lib/broadcast/application.ex`
- [Stream fan-out](https://github.com/teceer/pipsim/blob/main/services/broadcast/lib/broadcast/gateway_client.ex): `services/broadcast/lib/broadcast/gateway_client.ex`
- [World channels](https://github.com/teceer/pipsim/blob/main/services/broadcast/lib/broadcast/world_channel.ex): `services/broadcast/lib/broadcast/world_channel.ex`
- [BFF and jobs](https://github.com/teceer/pipsim/blob/main/services/bff/src/index.ts): `services/bff/src/index.ts`

### Simulation runtime

- [World gateway](https://github.com/teceer/pipsim/blob/main/services/world-gateway/internal/gateway/gateway.go): `services/world-gateway/internal/gateway/gateway.go`
- [Simulation server](https://github.com/teceer/pipsim/blob/main/services/sim-core/crates/server/src/main.rs): `services/sim-core/crates/server/src/main.rs`
- [Deterministic core](https://github.com/teceer/pipsim/blob/main/services/sim-core/crates/sim/src/lib.rs): `services/sim-core/crates/sim/src/lib.rs`

### Work and economy

- [Bank API](https://github.com/teceer/pipsim/blob/main/services/bank/internal/bankapi/bankapi.go): `services/bank/internal/bankapi/bankapi.go`
- [Ledger store](https://github.com/teceer/pipsim/blob/main/services/bank/internal/ledger/postgres.go): `services/bank/internal/ledger/postgres.go`
- [Economy driver](https://github.com/teceer/pipsim/blob/main/services/world-gateway/internal/economy/driver.go): `services/world-gateway/internal/economy/driver.go`
- [Farm workplace](https://github.com/teceer/pipsim/blob/main/services/workplaces/farm/internal/farm/farm.go): `services/workplaces/farm/internal/farm/farm.go`
- [Tavern workplace](https://github.com/teceer/pipsim/blob/main/services/workplaces/tavern/lib/tavern/workplace.ex): `services/workplaces/tavern/lib/tavern/workplace.ex`
- [Workshop workplace](https://github.com/teceer/pipsim/tree/main/services/workplaces/workshop): `services/workplaces/workshop`

### Service contracts

- [Protobuf contracts](https://github.com/teceer/pipsim/blob/main/proto/pips/world/v1/world.proto): `proto/pips/world/v1/world.proto`

### Other components

- **Player**
- **Kafka fact log**
- **RabbitMQ offers**

## Connections

- Player → Browser client: uses
- Browser client → World gateway: joins and streams
- Browser client → WASM predictor: predicts locally
- World gateway → Simulation server: requests world state
- Simulation server → Deterministic core: steps world
- Simulation server → Kafka fact log: publishes facts
- World gateway → Economy driver: drives economy
- Economy driver → Farm workplace: calls workplace
- Economy driver → Tavern workplace: calls workplace
- Economy driver → RabbitMQ offers: publishes offers
- RabbitMQ offers → Farm workplace: delivers offers
- RabbitMQ offers → Tavern workplace: delivers offers
- World gateway → Bank API: calls bank
- Bank API → Ledger store: reads and writes
- Bank API → Kafka fact log: publishes money facts
- Kafka fact log → Bank API: delivers lifecycle and purchases
- Broadcast service → Stream fan-out: starts client
- Stream fan-out → World gateway: streams world
- Stream fan-out → World channels: publishes deltas
- Browser client → World channels: subscribes
- BFF and jobs → RabbitMQ offers: schedules jobs