# robbyshao-8ag/yice architecture

> Architecture diagram of the GitHub repository robbyshao-8ag/yice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robbyshao-8ag/yice
- Repository: https://github.com/robbyshao-8ag/yice

## Overview

1. **Repository shape**
   - This is a Python-first decision-analysis system with two user-facing runtimes: a **CLI app** at `main.py` and a **web app** under `web/`.
   - The core product logic lives in `core/` and `agents/`; the rest is supporting data, tests, and generation scripts.

2. **Primary domain flow**
   - The central workflow is: **user question → clarification → scene classification → six-line analysis → report synthesis**.
   - The README describes this as a multi-agent “六爻” pipeline, and the code structure matches that: `QiguaAgent`, `SceneRouter`, `YaoAgents`, and `Reporter`.

3. **Agent orchestration layer**
   - `agents/` contains the conversational and reasoning roles:
     - `qigua_agent.py` handles question elicitation / divination-style intake.
     - `question_analyzer.py` and `sufficiency_checker.py` support whether the question is clear enough to proceed.
     - `scene_router.py` chooses a scenario/hexagram category.
     - `yao_agents.py` and `option_generator.py` drive the six parallel line-level analyses.
     - `reporter.py` assembles the final decision report.
   - This layer is the business logic boundary where LLM calls are coordinated.

4. **Core calculation and rule engine**
   - `core/` holds the deterministic domain logic around hexagrams and lines:
     - `bian_gua.py` for changing-hexagram logic,
     - `hu_gua.py` for inter-hexagram derivation,
     - `yao_math.py` for line/position calculations,
     - `liu_shou.py`, `hexagram_relations.py`, and related modules for traditional relationship rules.
   - This layer is the non-LLM “engine” that turns symbolic inputs into structured context for agents.

5. **Data model and loading**
   - Static knowledge is stored in `data/*.json`, including hexagrams, lines, scene mappings, yao attributes, and reference relations.
   - `core/data_loader.py` loads this data, while `core/models.py` defines the structured objects used across the pipeline.
   - `core/config_validator.py` validates runtime configuration, especially model/provider settings.

6. **LLM and external service boundary**
   - `core/llm_client.py` is the main integration point to external model providers.
   - The README shows provider/model configuration in `models.json`, which means the system is designed to swap LLM backends per agent rather than hard-coding a single model.
   - This is the key external dependency boundary: the reasoning pipeline is local, but generation steps depend on remote LLM APIs.

7. **CLI runtime**
   - `main.py` is the simplest entrypoint for local execution.
   - The README emphasizes a zero-dependency CLI path, so the CLI likely exercises the same core pipeline without the web frontend.
   - For architecture diagrams, treat this as a thin shell around `core.pipeline` and the agent layer.

8. **Web runtime**
   - `web/main.py` launches a separate web stack with a Python backend and a Vue/TypeScript frontend.
   - `web/backend/` exposes route handlers for config, history, and websocket dialogue; `services/agent_bridge.py` likely adapts backend requests into the core agent pipeline.
   - `web/frontend/` is a SPA built with Vue, Vite, TypeScript, stores, router, and a websocket client.

9. **Real-time interaction model**
   - The web app appears to use **WebSocket-based dialogue** for interactive questioning and staged analysis, not just one-shot requests.
   - `web/backend/routes/websocket.py` plus `web/frontend/src/services/websocket.ts` indicate streaming or stepwise updates during the divination/reporting process.
   - This matters because the user experience is conversational and incremental, not a single synchronous response.

10. **Persistence and history**
   - There is no obvious database in the tree; persistence is mostly file-based and transient.
   - Web-specific history support exists via `web/backend/routes/history.py`, suggesting session or conversation history is managed at the application layer, likely in memory or simple storage rather than a full DB.

11. **Testing and quality control**
   - The `tests/` directory is broad and highly specific: agent collaboration, pipeline, websocket dialogue, CLI, data integrity, hexagram rules, and LLM client behavior.
   - This indicates the architecture is heavily verified at both the deterministic-rule level and the orchestration level.
   - The `tests/fixtures/reference/` JSON files serve as canonical truth data for symbolic calculations.

12. **Build, maintenance, and CI**
   - `.github/workflows/ci.yml` provides continuous integration, and the `scripts/` folder contains data-generation and repair utilities.
   - Those scripts suggest part of the system’s “source of truth” is generated or normalized data, not just hand-written code.
   - For an architecture diagram, treat `scripts/` as the offline data-preparation layer feeding the runtime JSON knowledge base.

13. **Key boundaries to draw**
   - One boundary is between **symbolic/domain logic** (`core/` + `data/`) and **LLM-driven reasoning** (`agents/` + `llm_client.py`).
   - Another boundary is between **core engine** and **delivery channels**: CLI vs web backend/frontend.
   - The final boundary is **local code vs external model APIs**, since the system’s intelligence depends on remote providers but its structure and rules are local and deterministic.

Main entry points: [`core/pipeline.py`](https://github.com/robbyshao-8ag/yice/blob/master/core/pipeline.py) (Pipeline), [`agents/yao_agents.py`](https://github.com/robbyshao-8ag/yice/blob/master/agents/yao_agents.py) (Yao Agents), [`core/llm_client.py`](https://github.com/robbyshao-8ag/yice/blob/master/core/llm_client.py) (LLM Client), [`web/backend/main.py`](https://github.com/robbyshao-8ag/yice/blob/master/web/backend/main.py) (Web Backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_cli["CLI<br/>entrypoint<br/>[main.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_pipeline["Pipeline<br/>flow coordinator<br/>[pipeline.py]"]
  node_qigua_agent["Qigua<br/>intake agent<br/>[qigua_agent.py]"]
  node_question_analyzer["Analyzer<br/>question logic"]
  node_scene_router["Scene Router<br/>routing agent<br/>[scene_router.py]"]
  node_yao_agents["Yao Agents<br/>analysis agents<br/>[yao_agents.py]"]
  node_option_generator["Options<br/>prompt helper"]
  node_reporter["Reporter<br/>synthesizer<br/>[reporter.py]"]
  node_llm_client["LLM Client<br/>provider adapter<br/>[llm_client.py]"]
end

subgraph group_engine["Domain Engine"]
  node_hexagram_relations["Relations<br/>rule module"]
  node_bian_gua["Changing Gua<br/>rule module<br/>[bian_gua.py]"]
  node_hu_gua["Inter Gua<br/>rule module<br/>[hu_gua.py]"]
  node_yao_math["Yao Math<br/>calculation<br/>[yao_math.py]"]
  node_liu_shou["Liu Shou<br/>rule module<br/>[liu_shou.py]"]
end

subgraph group_knowledge["Knowledge"]
  node_models["Models<br/>schema<br/>[models.py]"]
  node_data_loader["Data Loader<br/>data access<br/>[data_loader.py]"]
  node_config_validator["Config Validator<br/>validation"]
  node_data[("Data JSON<br/>knowledge base<br/>[hexagrams.json]")]
end

subgraph group_web["Web Stack"]
  node_web_backend["Web Backend<br/>api server<br/>[main.py]"]
  node_agent_bridge["Agent Bridge<br/>adapter<br/>[agent_bridge.py]"]
  node_websocket_route["WebSocket<br/>route<br/>[websocket.py]"]
  node_history_route["History<br/>route<br/>[history.py]"]
  node_config_route["Config<br/>route<br/>[config.py]"]
  node_spa["Vue SPA<br/>frontend app<br/>[App.vue]"]
  node_websocket_client["WS Client<br/>frontend service<br/>[websocket.ts]"]
end

subgraph group_ops["Ops"]
  node_scripts["Scripts<br/>offline tooling<br/>[generate_data.py]"]
  node_tests["Tests<br/>verification<br/>[test_pipeline.py]"]
end

node_model_api(("Model APIs<br/>external service"))

node_cli -->|"runs"| node_pipeline
node_web_backend -->|"delegates"| node_agent_bridge
node_agent_bridge -->|"invokes"| node_pipeline
node_websocket_route -->|"streams"| node_agent_bridge
node_websocket_client -->|"connects"| node_websocket_route
node_pipeline -->|"asks"| node_qigua_agent
node_pipeline -->|"checks"| node_question_analyzer
node_pipeline -->|"routes"| node_scene_router
node_pipeline -->|"analyzes"| node_yao_agents
node_pipeline -->|"synthesizes"| node_reporter
node_qigua_agent -->|"calls"| node_llm_client
node_scene_router -->|"reads"| node_data_loader
node_scene_router -->|"uses"| node_hexagram_relations
node_yao_agents -->|"computes"| node_yao_math
node_yao_agents -->|"derives"| node_bian_gua
node_yao_agents -->|"derives"| node_hu_gua
node_yao_agents -->|"applies"| node_liu_shou
node_yao_agents -->|"calls"| node_llm_client
node_reporter -->|"formats"| node_models
node_reporter -->|"calls"| node_llm_client
node_pipeline -->|"passes"| node_models
node_data_loader -->|"loads"| node_data
node_config_validator -->|"validates"| node_models
node_llm_client -->|"requests"| node_model_api
node_web_backend -->|"exposes"| node_history_route
node_web_backend -->|"exposes"| node_config_route
node_web_backend -->|"exposes"| node_websocket_route
node_spa -->|"uses"| node_websocket_client
node_scripts -->|"generates"| node_data
node_tests -->|"verifies"| node_pipeline
node_tests -->|"verifies"| node_websocket_route
node_tests -->|"mocks"| node_llm_client
node_tests -->|"checks"| node_data_loader

click node_cli "https://github.com/robbyshao-8ag/yice/blob/master/main.py"
click node_pipeline "https://github.com/robbyshao-8ag/yice/blob/master/core/pipeline.py"
click node_qigua_agent "https://github.com/robbyshao-8ag/yice/blob/master/agents/qigua_agent.py"
click node_question_analyzer "https://github.com/robbyshao-8ag/yice/blob/master/agents/question_analyzer.py"
click node_scene_router "https://github.com/robbyshao-8ag/yice/blob/master/agents/scene_router.py"
click node_yao_agents "https://github.com/robbyshao-8ag/yice/blob/master/agents/yao_agents.py"
click node_option_generator "https://github.com/robbyshao-8ag/yice/blob/master/agents/option_generator.py"
click node_reporter "https://github.com/robbyshao-8ag/yice/blob/master/agents/reporter.py"
click node_llm_client "https://github.com/robbyshao-8ag/yice/blob/master/core/llm_client.py"
click node_models "https://github.com/robbyshao-8ag/yice/blob/master/core/models.py"
click node_data_loader "https://github.com/robbyshao-8ag/yice/blob/master/core/data_loader.py"
click node_config_validator "https://github.com/robbyshao-8ag/yice/blob/master/core/config_validator.py"
click node_hexagram_relations "https://github.com/robbyshao-8ag/yice/blob/master/core/hexagram_relations.py"
click node_bian_gua "https://github.com/robbyshao-8ag/yice/blob/master/core/bian_gua.py"
click node_hu_gua "https://github.com/robbyshao-8ag/yice/blob/master/core/hu_gua.py"
click node_yao_math "https://github.com/robbyshao-8ag/yice/blob/master/core/yao_math.py"
click node_liu_shou "https://github.com/robbyshao-8ag/yice/blob/master/core/liu_shou.py"
click node_web_backend "https://github.com/robbyshao-8ag/yice/blob/master/web/backend/main.py"
click node_agent_bridge "https://github.com/robbyshao-8ag/yice/blob/master/web/backend/services/agent_bridge.py"
click node_websocket_route "https://github.com/robbyshao-8ag/yice/blob/master/web/backend/routes/websocket.py"
click node_history_route "https://github.com/robbyshao-8ag/yice/blob/master/web/backend/routes/history.py"
click node_config_route "https://github.com/robbyshao-8ag/yice/blob/master/web/backend/routes/config.py"
click node_spa "https://github.com/robbyshao-8ag/yice/blob/master/web/frontend/src/App.vue"
click node_websocket_client "https://github.com/robbyshao-8ag/yice/blob/master/web/frontend/src/services/websocket.ts"
click node_scripts "https://github.com/robbyshao-8ag/yice/blob/master/scripts/generate_data.py"
click node_tests "https://github.com/robbyshao-8ag/yice/blob/master/tests/test_pipeline.py"
click node_data "https://github.com/robbyshao-8ag/yice/blob/master/data/hexagrams.json"

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_cli toneBlue
class node_pipeline,node_qigua_agent,node_question_analyzer,node_scene_router,node_yao_agents,node_option_generator,node_reporter,node_llm_client toneAmber
class node_hexagram_relations,node_bian_gua,node_hu_gua,node_yao_math,node_liu_shou toneMint
class node_models,node_data_loader,node_config_validator,node_data toneRose
class node_web_backend,node_agent_bridge,node_websocket_route,node_history_route,node_config_route,node_spa,node_websocket_client toneIndigo
class node_scripts,node_tests toneTeal
class node_model_api toneNeutral
```

## Components

### Delivery

CLI and web entrypoints exposed to users

- [CLI](https://github.com/robbyshao-8ag/yice/blob/master/main.py): entrypoint · Command-line entrypoint for local runs · `main.py`

### Orchestration

Question intake, routing, and report assembly

- [Pipeline](https://github.com/robbyshao-8ag/yice/blob/master/core/pipeline.py): flow coordinator · Coordinates the end-to-end divination workflow · `core/pipeline.py`
- [Qigua](https://github.com/robbyshao-8ag/yice/blob/master/agents/qigua_agent.py): intake agent · Collects and clarifies the user question · `agents/qigua_agent.py`
- [Analyzer](https://github.com/robbyshao-8ag/yice/blob/master/agents/question_analyzer.py): question logic · Checks whether the question is sufficiently clear · `agents/question_analyzer.py`
- [Scene Router](https://github.com/robbyshao-8ag/yice/blob/master/agents/scene_router.py): routing agent · Maps the question to a scene or hexagram category · `agents/scene_router.py`
- [Yao Agents](https://github.com/robbyshao-8ag/yice/blob/master/agents/yao_agents.py): analysis agents · Runs the six parallel line-level analyses · `agents/yao_agents.py`
- [Options](https://github.com/robbyshao-8ag/yice/blob/master/agents/option_generator.py): prompt helper · Generates candidate choices for analysis or response · `agents/option_generator.py`
- [Reporter](https://github.com/robbyshao-8ag/yice/blob/master/agents/reporter.py): synthesizer · Assembles the final decision report · `agents/reporter.py`
- [LLM Client](https://github.com/robbyshao-8ag/yice/blob/master/core/llm_client.py): provider adapter · Single integration point for external model providers · `core/llm_client.py`

### Domain Engine

Deterministic hexagram and line calculations

- [Relations](https://github.com/robbyshao-8ag/yice/blob/master/core/hexagram_relations.py): rule module · Traditional relationship rules for hexagrams and lines · `core/hexagram_relations.py`
- [Changing Gua](https://github.com/robbyshao-8ag/yice/blob/master/core/bian_gua.py): rule module · Computes the changing hexagram · `core/bian_gua.py`
- [Inter Gua](https://github.com/robbyshao-8ag/yice/blob/master/core/hu_gua.py): rule module · Derives the inter-hexagram structure · `core/hu_gua.py`
- [Yao Math](https://github.com/robbyshao-8ag/yice/blob/master/core/yao_math.py): calculation · Calculates line and position values · `core/yao_math.py`
- [Liu Shou](https://github.com/robbyshao-8ag/yice/blob/master/core/liu_shou.py): rule module · Applies six-spirit relationship logic · `core/liu_shou.py`

### Knowledge

Static reference data and loaders

- [Models](https://github.com/robbyshao-8ag/yice/blob/master/core/models.py): schema · Shared structured objects passed through the pipeline · `core/models.py`
- [Data Loader](https://github.com/robbyshao-8ag/yice/blob/master/core/data_loader.py): data access · Loads static hexagram and relation knowledge · `core/data_loader.py`
- [Config Validator](https://github.com/robbyshao-8ag/yice/blob/master/core/config_validator.py): validation · Checks runtime model and provider configuration · `core/config_validator.py`
- [Data JSON](https://github.com/robbyshao-8ag/yice/blob/master/data/hexagrams.json): knowledge base · Static hexagram, scene, and relation reference data · `data/hexagrams.json`

### Web Stack

Backend API and Vue frontend

- [Web Backend](https://github.com/robbyshao-8ag/yice/blob/master/web/backend/main.py): api server · Python backend for routes and dialogue orchestration · `web/backend/main.py`
- [Agent Bridge](https://github.com/robbyshao-8ag/yice/blob/master/web/backend/services/agent_bridge.py): adapter · Adapts web requests into the core pipeline · `web/backend/services/agent_bridge.py`
- [WebSocket](https://github.com/robbyshao-8ag/yice/blob/master/web/backend/routes/websocket.py): route · Handles staged conversational updates · `web/backend/routes/websocket.py`
- [History](https://github.com/robbyshao-8ag/yice/blob/master/web/backend/routes/history.py): route · Serves dialogue and session history · `web/backend/routes/history.py`
- [Config](https://github.com/robbyshao-8ag/yice/blob/master/web/backend/routes/config.py): route · Exposes configuration endpoints for the web app · `web/backend/routes/config.py`
- [Vue SPA](https://github.com/robbyshao-8ag/yice/blob/master/web/frontend/src/App.vue): frontend app · Single-page web client for interactive divination · `web/frontend/src/App.vue`
- [WS Client](https://github.com/robbyshao-8ag/yice/blob/master/web/frontend/src/services/websocket.ts): frontend service · Client-side websocket transport for dialogue · `web/frontend/src/services/websocket.ts`

### Ops

Offline generation and verification

- [Scripts](https://github.com/robbyshao-8ag/yice/blob/master/scripts/generate_data.py): offline tooling · Generates and repairs reference knowledge data · `scripts/generate_data.py`
- [Tests](https://github.com/robbyshao-8ag/yice/blob/master/tests/test_pipeline.py): verification · Covers pipeline, rules, websocket, CLI, and data integrity · `tests/test_pipeline.py`

### Other components

- **Model APIs**: external service · Remote LLM providers used by the agents

## Connections

- CLI → Pipeline: runs · CLI invokes the shared workflow
- Web Backend → Agent Bridge: delegates · Web backend hands requests to the core pipeline adapter
- Agent Bridge → Pipeline: invokes · Bridges web requests into the shared orchestration flow
- WebSocket → Agent Bridge: streams · WebSocket route drives incremental dialogue execution
- WS Client → WebSocket: connects · Frontend dialogue client talks to the backend websocket endpoint
- Pipeline → Qigua: asks · Pipeline starts by eliciting and clarifying the question
- Pipeline → Analyzer: checks · Ensures the question is clear enough to proceed
- Pipeline → Scene Router: routes · Selects the scenario or hexagram category
- Pipeline → Yao Agents: analyzes · Launches the six line-level analyses
- Pipeline → Reporter: synthesizes · Produces the final decision report
- Qigua → LLM Client: calls · Uses model calls for conversational intake
- Scene Router → Data Loader: reads · Uses reference mappings to classify the scene
- Scene Router → Relations: uses · Applies symbolic relation rules during routing
- Yao Agents → Yao Math: computes · Derives line-level positions and values
- Yao Agents → Changing Gua: derives · Builds changing-hexagram context
- Yao Agents → Inter Gua: derives · Builds inter-hexagram context
- Yao Agents → Liu Shou: applies · Adds six-spirit relationship context
- Yao Agents → LLM Client: calls · Combines deterministic context with model reasoning
- Reporter → Models: formats · Assembles structured output from shared models
- Reporter → LLM Client: calls · May use models for final synthesis and phrasing
- Pipeline → Models: passes · Pipeline moves typed objects between stages
- Data Loader → Data JSON: loads · Reads the static knowledge base
- Config Validator → Models: validates · Checks provider and model configuration against schema
- LLM Client → Model APIs: requests · External dependency boundary to remote model providers
- Web Backend → History: exposes · Serves conversation history endpoints
- Web Backend → Config: exposes · Serves configuration endpoints
- Web Backend → WebSocket: exposes · Serves interactive websocket dialogue
- Vue SPA → WS Client: uses · Frontend UI relies on websocket transport
- Scripts → Data JSON: generates · Offline scripts create and repair reference data
- Tests → Pipeline: verifies · Tests the main workflow end to end
- Tests → WebSocket: verifies · Tests interactive websocket dialogue behavior
- Tests → LLM Client: mocks · Validates provider integration behavior
- Tests → Data Loader: checks · Covers data loading and integrity rules
