# uripros/os-project architecture

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

- Interactive diagram: https://gitdiagram.com/uripros/os-project
- Repository: https://github.com/uripros/os-project

## Overview

The Citadel System is a C program that runs one Maester process per realm. Its main workflow loads realm configuration and stock, starts network and envoy workers, and provides commands for realm/product listing, pledges, envoy status, and trade sessions. Envoys handle delegated missions; socket framing and network handlers support communication between realms. The README describes these capabilities, but source excerpts are limited, so links between command routing and specific handlers are documented rather than verified from call sites.

Main entry points: [`maester.c`](https://github.com/uripros/os-project/blob/main/maester.c) (Maester process), [`COMMANDS/detectCommand.c`](https://github.com/uripros/os-project/blob/main/COMMANDS/detectCommand.c) (Command detection), [`CONFIG/envoyConfig.c`](https://github.com/uripros/os-project/blob/main/CONFIG/envoyConfig.c) (Envoy configuration), [`CONFIG/localConfig.c`](https://github.com/uripros/os-project/blob/main/CONFIG/localConfig.c) (Local configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Maester runtime"]
  node_maester["Maester process<br/>[maester.c]"]
  node_localconfig["Local configuration<br/>[localConfig.c]"]
  node_utilities["Shared utilities<br/>[utils.c]"]
end

subgraph group_commands["User commands"]
  node_dispatcher["Command detection<br/>[detectCommand.c]"]
  node_listing["Listing commands<br/>[listComm.c]"]
  node_pledges["Pledge commands<br/>[pledgeComm.c]"]
  node_envoycommands["Envoy commands<br/>[envoyComm.c]"]
  node_tradecommands["Trade commands<br/>[startComm.c]"]
  node_tradefunctions["Trade operations<br/>[tradeFunc.c]"]
end

subgraph group_envoys["Envoy operations"]
  node_envoyconfig["Envoy configuration<br/>[envoyConfig.c]"]
  node_envoyworker["Envoy missions<br/>[envoyConfig.c]"]
end

subgraph group_network["Realm networking"]
  node_networkconfig["Network configuration<br/>[networkConfig.c]"]
  node_frame["Frame management<br/>[frame.c]"]
  node_threadhandler["Received-frame handlers<br/>[threadHandler.c]"]
end

subgraph group_realmdata["Realm data"]
  node_realmstate["Realm configuration"]
  node_stock[("Product stock")]
end

node_user(("Operator"))

node_user -->|"starts"| node_maester
node_maester -->|"loads configuration"| node_localconfig
node_maester -->|"loads stock"| node_stock
node_maester -->|"creates envoys"| node_envoyconfig
node_maester -->|"starts network worker"| node_networkconfig
node_maester -->|"starts envoy worker"| node_envoyconfig
node_maester -.->|"runs commands"| node_dispatcher
node_dispatcher -->|"routes listing"| node_listing
node_dispatcher -->|"routes pledges"| node_pledges
node_dispatcher -->|"routes envoy status"| node_envoycommands
node_dispatcher -->|"routes trades"| node_tradecommands
node_tradecommands -->|"delegates trade work"| node_tradefunctions
node_networkconfig -.->|"handles network traffic"| node_threadhandler
node_threadhandler -.->|"processes frames"| node_frame
node_envoyconfig -.->|"dispatches missions"| node_envoyworker
node_localconfig -->|"reads realm settings"| node_realmstate
node_utilities -.->|"provides shared functions"| node_maester

click node_maester "https://github.com/uripros/os-project/blob/main/maester.c"
click node_localconfig "https://github.com/uripros/os-project/blob/main/CONFIG/localConfig.c"
click node_networkconfig "https://github.com/uripros/os-project/blob/main/CONFIG/networkConfig.c"
click node_envoyconfig "https://github.com/uripros/os-project/blob/main/CONFIG/envoyConfig.c"
click node_dispatcher "https://github.com/uripros/os-project/blob/main/COMMANDS/detectCommand.c"
click node_listing "https://github.com/uripros/os-project/blob/main/COMMANDS/LIST/listComm.c"
click node_pledges "https://github.com/uripros/os-project/blob/main/COMMANDS/PLEDGE/pledgeComm.c"
click node_envoycommands "https://github.com/uripros/os-project/blob/main/COMMANDS/ENVOY/envoyComm.c"
click node_tradecommands "https://github.com/uripros/os-project/blob/main/COMMANDS/START/startComm.c"
click node_tradefunctions "https://github.com/uripros/os-project/blob/main/COMMANDS/START/tradeFunc.c"
click node_frame "https://github.com/uripros/os-project/blob/main/SOCKET/frame.c"
click node_threadhandler "https://github.com/uripros/os-project/blob/main/SOCKET/threadHandler.c"
click node_envoyworker "https://github.com/uripros/os-project/blob/main/CONFIG/envoyConfig.c"
click node_realmstate "https://github.com/uripros/os-project/tree/main/REALMS"
click node_stock "https://github.com/uripros/os-project/tree/main/REALMS"
click node_utilities "https://github.com/uripros/os-project/blob/main/utils.c"

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_maester,node_localconfig,node_utilities toneBlue
class node_dispatcher,node_listing,node_pledges,node_envoycommands,node_tradecommands,node_tradefunctions toneAmber
class node_envoyconfig,node_envoyworker toneMint
class node_networkconfig,node_frame,node_threadhandler toneRose
class node_realmstate,node_stock,node_user toneIndigo
```

## Components

### Maester runtime

- [Maester process](https://github.com/uripros/os-project/blob/main/maester.c): `maester.c`
- [Local configuration](https://github.com/uripros/os-project/blob/main/CONFIG/localConfig.c): `CONFIG/localConfig.c`
- [Shared utilities](https://github.com/uripros/os-project/blob/main/utils.c): `utils.c`

### User commands

- [Command detection](https://github.com/uripros/os-project/blob/main/COMMANDS/detectCommand.c): `COMMANDS/detectCommand.c`
- [Listing commands](https://github.com/uripros/os-project/blob/main/COMMANDS/LIST/listComm.c): `COMMANDS/LIST/listComm.c`
- [Pledge commands](https://github.com/uripros/os-project/blob/main/COMMANDS/PLEDGE/pledgeComm.c): `COMMANDS/PLEDGE/pledgeComm.c`
- [Envoy commands](https://github.com/uripros/os-project/blob/main/COMMANDS/ENVOY/envoyComm.c): `COMMANDS/ENVOY/envoyComm.c`
- [Trade commands](https://github.com/uripros/os-project/blob/main/COMMANDS/START/startComm.c): `COMMANDS/START/startComm.c`
- [Trade operations](https://github.com/uripros/os-project/blob/main/COMMANDS/START/tradeFunc.c): `COMMANDS/START/tradeFunc.c`

### Envoy operations

- [Envoy configuration](https://github.com/uripros/os-project/blob/main/CONFIG/envoyConfig.c): `CONFIG/envoyConfig.c`
- [Envoy missions](https://github.com/uripros/os-project/blob/main/CONFIG/envoyConfig.c): `CONFIG/envoyConfig.c`

### Realm networking

- [Network configuration](https://github.com/uripros/os-project/blob/main/CONFIG/networkConfig.c): `CONFIG/networkConfig.c`
- [Frame management](https://github.com/uripros/os-project/blob/main/SOCKET/frame.c): `SOCKET/frame.c`
- [Received-frame handlers](https://github.com/uripros/os-project/blob/main/SOCKET/threadHandler.c): `SOCKET/threadHandler.c`

### Realm data

- [Realm configuration](https://github.com/uripros/os-project/tree/main/REALMS): `REALMS`
- [Product stock](https://github.com/uripros/os-project/tree/main/REALMS): `REALMS`

### Other components

- **Operator**

## Connections

- Operator → Maester process: starts (evidence: `README.txt`)
- Maester process → Local configuration: loads configuration (evidence: `maester.c`)
- Maester process → Product stock: loads stock (evidence: `maester.c`)
- Maester process → Envoy configuration: creates envoys (evidence: `maester.c`)
- Maester process → Network configuration: starts network worker (evidence: `maester.c`)
- Maester process → Envoy configuration: starts envoy worker (evidence: `maester.c`)
- Maester process → Command detection: runs commands (evidence: `README.txt`)
- Command detection → Listing commands: routes listing (evidence: `README.txt`)
- Command detection → Pledge commands: routes pledges (evidence: `README.txt`)
- Command detection → Envoy commands: routes envoy status (evidence: `README.txt`)
- Command detection → Trade commands: routes trades (evidence: `README.txt`)
- Trade commands → Trade operations: delegates trade work (evidence: `COMMANDS/START/startComm.c`)
- Network configuration → Received-frame handlers: handles network traffic
- Received-frame handlers → Frame management: processes frames
- Envoy configuration → Envoy missions: dispatches missions (evidence: `CONFIG/envoyConfig.c`)
- Local configuration → Realm configuration: reads realm settings (evidence: `README.txt`)
- Shared utilities → Maester process: provides shared functions