# richard2606-hub/guildhouse architecture

> Architecture diagram of the GitHub repository richard2606-hub/guildhouse, 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/richard2606-hub/guildhouse
- Repository: https://github.com/richard2606-hub/guildhouse

## Overview

GuildHouse is a privacy-focused AI clerk platform: users select a YAML-defined clerk, submit a request through the web console, and receive a response with confidence/escalation and audit metadata. The session manager owns the request lifecycle, including safety checks, tools, retrieval, inference, and final rendering; the web app also exposes pack management and pipeline inspection. The graph follows README-documented stages and sampled call sites; unsampled frontend API wiring and some internal stage details are represented only where documentation supports them.

Main entry points: [`backend/engine/session.py`](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/session.py) (Session Pipeline), [`backend/main.py`](https://github.com/richard2606-hub/guildhouse/blob/main/backend/main.py) (FastAPI API), [`frontend/src/App.jsx`](https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/App.jsx) (Console App), [`backend/engine/inference.py`](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/inference.py) (Local Draft Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Console"]
  node_app["Console App<br/>[App.jsx]"]
  node_console["Live Console<br/>[Console.jsx]"]
  node_catalog["Pack Catalog<br/>[Catalog.jsx]"]
  node_studio["Pack Studio<br/>[PackStudio.jsx]"]
  node_inspector["Pipeline Inspector<br/>[Inspector.jsx]"]
end

subgraph group_api["API And Packs"]
  node_api["FastAPI API<br/>[main.py]"]
end

subgraph group_runtime["Clerk Runtime"]
  node_loader["Pack Loader<br/>[loader.py]"]
  node_packs["YAML Packs"]
  node_session["Session Pipeline<br/>[session.py]"]
  node_rules["Safety Rules<br/>[rules.py]"]
  node_tools["Pack Tools<br/>[tools.py]"]
  node_retrieval["Knowledge Retrieval<br/>[retrieval.py]"]
  node_persona["Persona Rendering<br/>[persona.py]"]
end

subgraph group_integrations["Inference And Audit"]
  node_inference["Local Draft Engine<br/>[inference.py]"]
  node_gateway["Escalation Gateway<br/>[gateway.py]"]
  node_ledger[("Audit Ledger<br/>[ledger.py]")]
  node_fireworks{{"Fireworks AI"}}
  node_gemini{{"Google Gemini"}}
end

node_user(("Clerk User"))

node_user -->|"submits request"| node_console
node_app -->|"selects view"| node_console
node_app -->|"selects view"| node_catalog
node_app -->|"selects view"| node_studio
node_app -->|"selects view"| node_inspector
node_console -->|"sends chat"| node_api
node_catalog -->|"manages packs"| node_api
node_studio -->|"edits packs"| node_api
node_inspector -->|"reads trace"| node_api
node_api -->|"processes request"| node_session
node_api -->|"serves pack data"| node_loader
node_api -->|"reads ledger"| node_ledger
node_loader -->|"loads manifests"| node_packs
node_session -->|"gets clerk pack"| node_loader
node_session -->|"checks input"| node_rules
node_session -->|"detects tool intent"| node_tools
node_session -->|"retrieves context"| node_retrieval
node_session -->|"generates draft"| node_inference
node_session -->|"escalates draft"| node_gateway
node_session -->|"validates answer"| node_rules
node_session -->|"renders response"| node_persona
node_session -->|"logs events"| node_ledger
node_inference -.->|"requests inference"| node_fireworks
node_inference -.->|"requests inference"| node_gemini
node_gateway -.->|"requests escalation"| node_fireworks
node_gateway -.->|"requests escalation"| node_gemini

click node_app "https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/App.jsx"
click node_console "https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/Console.jsx"
click node_catalog "https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/Catalog.jsx"
click node_studio "https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/PackStudio.jsx"
click node_inspector "https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/Inspector.jsx"
click node_api "https://github.com/richard2606-hub/guildhouse/blob/main/backend/main.py"
click node_loader "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/loader.py"
click node_packs "https://github.com/richard2606-hub/guildhouse/tree/main/backend/packs"
click node_session "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/session.py"
click node_rules "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/rules.py"
click node_tools "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/tools.py"
click node_retrieval "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/retrieval.py"
click node_persona "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/persona.py"
click node_inference "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/inference.py"
click node_gateway "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/gateway.py"
click node_ledger "https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/ledger.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_app,node_console,node_catalog,node_studio,node_inspector,node_user toneBlue
class node_api toneAmber
class node_loader,node_packs,node_session,node_rules,node_tools,node_retrieval,node_persona toneMint
class node_inference,node_gateway,node_ledger,node_fireworks,node_gemini toneRose
```

## Components

### Web Console

- [Console App](https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Live Console](https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/Console.jsx): `frontend/src/views/Console.jsx`
- [Pack Catalog](https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/Catalog.jsx): `frontend/src/views/Catalog.jsx`
- [Pack Studio](https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/PackStudio.jsx): `frontend/src/views/PackStudio.jsx`
- [Pipeline Inspector](https://github.com/richard2606-hub/guildhouse/blob/main/frontend/src/views/Inspector.jsx): `frontend/src/views/Inspector.jsx`

### API And Packs

- [FastAPI API](https://github.com/richard2606-hub/guildhouse/blob/main/backend/main.py): `backend/main.py`

### Clerk Runtime

- [Pack Loader](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/loader.py): `backend/engine/loader.py`
- [YAML Packs](https://github.com/richard2606-hub/guildhouse/tree/main/backend/packs): `backend/packs`
- [Session Pipeline](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/session.py): `backend/engine/session.py`
- [Safety Rules](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/rules.py): `backend/engine/rules.py`
- [Pack Tools](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/tools.py): `backend/engine/tools.py`
- [Knowledge Retrieval](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/retrieval.py): `backend/engine/retrieval.py`
- [Persona Rendering](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/persona.py): `backend/engine/persona.py`

### Inference And Audit

- [Local Draft Engine](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/inference.py): `backend/engine/inference.py`
- [Escalation Gateway](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/gateway.py): `backend/engine/gateway.py`
- [Audit Ledger](https://github.com/richard2606-hub/guildhouse/blob/main/backend/engine/ledger.py): `backend/engine/ledger.py`
- **Fireworks AI**
- **Google Gemini**

### Other components

- **Clerk User**

## Connections

- Clerk User → Live Console: submits request
- Console App → Live Console: selects view
- Console App → Pack Catalog: selects view
- Console App → Pack Studio: selects view
- Console App → Pipeline Inspector: selects view
- Live Console → FastAPI API: sends chat
- Pack Catalog → FastAPI API: manages packs
- Pack Studio → FastAPI API: edits packs
- Pipeline Inspector → FastAPI API: reads trace
- FastAPI API → Session Pipeline: processes request
- FastAPI API → Pack Loader: serves pack data
- FastAPI API → Audit Ledger: reads ledger
- Pack Loader → YAML Packs: loads manifests
- Session Pipeline → Pack Loader: gets clerk pack
- Session Pipeline → Safety Rules: checks input
- Session Pipeline → Pack Tools: detects tool intent
- Session Pipeline → Knowledge Retrieval: retrieves context
- Session Pipeline → Local Draft Engine: generates draft
- Session Pipeline → Escalation Gateway: escalates draft
- Session Pipeline → Safety Rules: validates answer
- Session Pipeline → Persona Rendering: renders response
- Session Pipeline → Audit Ledger: logs events
- Local Draft Engine → Fireworks AI: requests inference
- Local Draft Engine → Google Gemini: requests inference
- Escalation Gateway → Fireworks AI: requests escalation
- Escalation Gateway → Google Gemini: requests escalation