# sii-research/legal-world architecture

> Architecture diagram of the GitHub repository sii-research/legal-world, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sii-research/legal-world
- Repository: https://github.com/sii-research/legal-world

## Overview

LEGALWORLD is an interactive legal-agent simulation spanning consultation, document drafting, first-instance trial, appeal, and second-instance proceedings. A run enters through the WebSocket/API service, which coordinates case scenarios and agents; the life-cycle pipeline supplies staged execution and Tool/Skill resolution. Supporting capabilities include simulation frontend messaging, human evaluation, legal retrieval, and reflective Skill growth. The README also documents dataset construction utilities, represented as a distinct reproducibility branch. Several subsystem links are documented by README rather than inspected implementation; unsampled runtime links are omitted.

Main entry points: [`backend/src/orchestration/scenario_orchestrator.py`](https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/scenario_orchestrator.py) (Scenario orchestrator), [`backend/ws_server.py`](https://github.com/sii-research/legal-world/blob/main/backend/ws_server.py) (API & WebSocket), [`backend/src/agents`](https://github.com/sii-research/legal-world/tree/main/backend/src/agents) (Legal agent wrappers), [`backend/src/pipeline/pipeline.py`](https://github.com/sii-research/legal-world/blob/main/backend/src/pipeline/pipeline.py) (Lifecycle pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Service &amp; coordination"]
  node_web["API &amp; WebSocket<br/>[ws_server.py]"]
  node_fsm["Case lifecycle FSM<br/>[case_fsm.py]"]
  node_orchestrator["Scenario orchestrator"]
  node_registry["Agent registry<br/>[agent_registry.py]"]
end

subgraph group_lifecycle["Legal case lifecycle"]
  node_dataset["Case data loader<br/>[data_loader.py]"]
  node_pipeline["Lifecycle pipeline<br/>[pipeline.py]"]
  node_stage_resolver["Stage Tool resolver"]
  node_scenarios["Legal scenarios"]
end

subgraph group_agent_tools["Agents &amp; legal tools"]
  node_agents["Legal agent wrappers"]
  node_prompting["Prompt assembly"]
  node_legal_tools["Legal Tool suite"]
  node_skills["Skill library"]
  node_player_lawyer["Player lawyer adapter<br/>[agent.py]"]
end

subgraph group_state_sim["State &amp; simulation"]
  node_eventbus["Event bus<br/>[event_bus.py]"]
  node_storage[("Case file storage")]
  node_simulation["WebSocket simulation"]
  node_map["Mock map engine<br/>[map_engine.py]"]
end

subgraph group_research["Research utilities"]
  node_human_eval["Human evaluation<br/>[routes.py]"]
  node_eval["Evaluation pipeline<br/>[eval_pipeline.py]"]
  node_skill_growth["Reflective Skill growth<br/>[pipeline.py]"]
  node_builder["Case dataset builder<br/>[pipeline.py]"]
end

node_user(("User / client"))
node_postgres[("PostgreSQL")]
node_model{{"Model provider"}}
node_frontend(("Simulation frontend"))

node_user -->|"requests cases"| node_web
node_web -->|"routes lifecycle"| node_fsm
node_web -->|"starts scenarios"| node_orchestrator
node_web -->|"serves evaluation routes"| node_human_eval
node_web -.->|"persists service data"| node_postgres
node_fsm -->|"publishes events"| node_eventbus
node_orchestrator -->|"subscribes and publishes"| node_eventbus
node_orchestrator -->|"looks up agents"| node_registry
node_orchestrator -->|"loads case data"| node_dataset
node_orchestrator -->|"builds prompts"| node_prompting
node_registry -->|"instantiates wrappers"| node_agents
node_registry -->|"reads agent configs"| node_storage
node_pipeline -->|"loads cases"| node_dataset
node_pipeline -->|"resolves stage tools"| node_stage_resolver
node_pipeline -->|"runs lifecycle stages"| node_scenarios
node_stage_resolver -->|"selects tools"| node_legal_tools
node_agents -->|"assembles prompts"| node_prompting
node_agents -.->|"invokes tools"| node_legal_tools
node_agents -->|"uses Skills"| node_skills
node_orchestrator -->|"adapts player counsel"| node_player_lawyer
node_orchestrator -->|"records case outputs"| node_storage
node_simulation -->|"sends simulation messages"| node_frontend
node_simulation -->|"uses fallback behavior"| node_map
node_human_eval -.->|"stores ratings"| node_postgres
node_eval -->|"loads evaluation cases"| node_dataset
node_skill_growth -->|"creates reflection lawyer"| node_agents
node_builder -->|"generates profiles and questions"| node_model

click node_web "https://github.com/sii-research/legal-world/blob/main/backend/ws_server.py"
click node_fsm "https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/case_fsm.py"
click node_orchestrator "https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/scenario_orchestrator.py"
click node_registry "https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/agent_registry.py"
click node_eventbus "https://github.com/sii-research/legal-world/blob/main/backend/src/core/event_bus.py"
click node_storage "https://github.com/sii-research/legal-world/blob/main/backend/src/core/file_storage_manager.py"
click node_dataset "https://github.com/sii-research/legal-world/blob/main/backend/src/data/data_loader.py"
click node_pipeline "https://github.com/sii-research/legal-world/blob/main/backend/src/pipeline/pipeline.py"
click node_stage_resolver "https://github.com/sii-research/legal-world/blob/main/backend/src/pipeline/stage_tool_resolver.py"
click node_scenarios "https://github.com/sii-research/legal-world/tree/main/backend/src/scenarios"
click node_agents "https://github.com/sii-research/legal-world/tree/main/backend/src/agents"
click node_prompting "https://github.com/sii-research/legal-world/blob/main/backend/src/prompts/prompt_assembler.py"
click node_legal_tools "https://github.com/sii-research/legal-world/tree/main/backend/src/tools/legal"
click node_skills "https://github.com/sii-research/legal-world/tree/main/backend/legal-skillhub/public"
click node_player_lawyer "https://github.com/sii-research/legal-world/blob/main/backend/src/player_lawyer/agent.py"
click node_simulation "https://github.com/sii-research/legal-world/blob/main/backend/src/simulation/ws_frontend_engine.py"
click node_map "https://github.com/sii-research/legal-world/blob/main/backend/src/simulation/map_engine.py"
click node_human_eval "https://github.com/sii-research/legal-world/blob/main/backend/src/human_eval/routes.py"
click node_eval "https://github.com/sii-research/legal-world/blob/main/backend/src/eval/eval_pipeline.py"
click node_skill_growth "https://github.com/sii-research/legal-world/blob/main/backend/gitskill/pipeline.py"
click node_builder "https://github.com/sii-research/legal-world/blob/main/dataset_builder/case_dataset_builder/pipeline.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_web,node_fsm,node_orchestrator,node_registry,node_user,node_frontend toneBlue
class node_dataset,node_pipeline,node_stage_resolver,node_scenarios,node_postgres toneAmber
class node_agents,node_prompting,node_legal_tools,node_skills,node_player_lawyer toneMint
class node_eventbus,node_storage,node_simulation,node_map toneRose
class node_human_eval,node_eval,node_skill_growth,node_builder,node_model toneIndigo
```

## Components

### Service & coordination

- [API & WebSocket](https://github.com/sii-research/legal-world/blob/main/backend/ws_server.py): `backend/ws_server.py`
- [Case lifecycle FSM](https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/case_fsm.py): `backend/src/orchestration/case_fsm.py`
- [Scenario orchestrator](https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/scenario_orchestrator.py): `backend/src/orchestration/scenario_orchestrator.py`
- [Agent registry](https://github.com/sii-research/legal-world/blob/main/backend/src/orchestration/agent_registry.py): `backend/src/orchestration/agent_registry.py`

### Legal case lifecycle

- [Case data loader](https://github.com/sii-research/legal-world/blob/main/backend/src/data/data_loader.py): `backend/src/data/data_loader.py`
- [Lifecycle pipeline](https://github.com/sii-research/legal-world/blob/main/backend/src/pipeline/pipeline.py): `backend/src/pipeline/pipeline.py`
- [Stage Tool resolver](https://github.com/sii-research/legal-world/blob/main/backend/src/pipeline/stage_tool_resolver.py): `backend/src/pipeline/stage_tool_resolver.py`
- [Legal scenarios](https://github.com/sii-research/legal-world/tree/main/backend/src/scenarios): `backend/src/scenarios`

### Agents & legal tools

- [Legal agent wrappers](https://github.com/sii-research/legal-world/tree/main/backend/src/agents): `backend/src/agents`
- [Prompt assembly](https://github.com/sii-research/legal-world/blob/main/backend/src/prompts/prompt_assembler.py): `backend/src/prompts/prompt_assembler.py`
- [Legal Tool suite](https://github.com/sii-research/legal-world/tree/main/backend/src/tools/legal): `backend/src/tools/legal`
- [Skill library](https://github.com/sii-research/legal-world/tree/main/backend/legal-skillhub/public): `backend/legal-skillhub/public`
- [Player lawyer adapter](https://github.com/sii-research/legal-world/blob/main/backend/src/player_lawyer/agent.py): `backend/src/player_lawyer/agent.py`

### State & simulation

- [Event bus](https://github.com/sii-research/legal-world/blob/main/backend/src/core/event_bus.py): `backend/src/core/event_bus.py`
- [Case file storage](https://github.com/sii-research/legal-world/blob/main/backend/src/core/file_storage_manager.py): `backend/src/core/file_storage_manager.py`
- [WebSocket simulation](https://github.com/sii-research/legal-world/blob/main/backend/src/simulation/ws_frontend_engine.py): `backend/src/simulation/ws_frontend_engine.py`
- [Mock map engine](https://github.com/sii-research/legal-world/blob/main/backend/src/simulation/map_engine.py): `backend/src/simulation/map_engine.py`

### Research utilities

- [Human evaluation](https://github.com/sii-research/legal-world/blob/main/backend/src/human_eval/routes.py): `backend/src/human_eval/routes.py`
- [Evaluation pipeline](https://github.com/sii-research/legal-world/blob/main/backend/src/eval/eval_pipeline.py): `backend/src/eval/eval_pipeline.py`
- [Reflective Skill growth](https://github.com/sii-research/legal-world/blob/main/backend/gitskill/pipeline.py): `backend/gitskill/pipeline.py`
- [Case dataset builder](https://github.com/sii-research/legal-world/blob/main/dataset_builder/case_dataset_builder/pipeline.py): `dataset_builder/case_dataset_builder/pipeline.py`

### Other components

- **User / client**
- **PostgreSQL**
- **Model provider**
- **Simulation frontend**

## Connections

- User / client → API & WebSocket: requests cases
- API & WebSocket → Case lifecycle FSM: routes lifecycle (evidence: `backend/ws_server.py`)
- API & WebSocket → Scenario orchestrator: starts scenarios (evidence: `backend/ws_server.py`)
- API & WebSocket → Human evaluation: serves evaluation routes (evidence: `backend/ws_server.py`)
- API & WebSocket → PostgreSQL: persists service data
- Case lifecycle FSM → Event bus: publishes events (evidence: `backend/src/orchestration/case_fsm.py`)
- Scenario orchestrator → Event bus: subscribes and publishes (evidence: `backend/src/orchestration/scenario_orchestrator.py`)
- Scenario orchestrator → Agent registry: looks up agents (evidence: `backend/src/orchestration/scenario_orchestrator.py`)
- Scenario orchestrator → Case data loader: loads case data (evidence: `backend/src/orchestration/scenario_orchestrator.py`)
- Scenario orchestrator → Prompt assembly: builds prompts (evidence: `backend/src/orchestration/scenario_orchestrator.py`)
- Agent registry → Legal agent wrappers: instantiates wrappers (evidence: `backend/src/orchestration/agent_registry.py`)
- Agent registry → Case file storage: reads agent configs (evidence: `backend/src/orchestration/agent_registry.py`)
- Lifecycle pipeline → Case data loader: loads cases (evidence: `backend/src/pipeline/pipeline.py`)
- Lifecycle pipeline → Stage Tool resolver: resolves stage tools (evidence: `backend/src/pipeline/pipeline.py`)
- Lifecycle pipeline → Legal scenarios: runs lifecycle stages (evidence: `backend/src/pipeline/pipeline.py`)
- Stage Tool resolver → Legal Tool suite: selects tools (evidence: `backend/src/pipeline/stage_tool_resolver.py`)
- Legal agent wrappers → Prompt assembly: assembles prompts (evidence: `backend/src/agents/client_agent.py`)
- Legal agent wrappers → Legal Tool suite: invokes tools
- Legal agent wrappers → Skill library: uses Skills
- Scenario orchestrator → Player lawyer adapter: adapts player counsel (evidence: `backend/src/orchestration/scenario_orchestrator.py`)
- Scenario orchestrator → Case file storage: records case outputs (evidence: `backend/src/orchestration/scenario_orchestrator.py`)
- WebSocket simulation → Simulation frontend: sends simulation messages
- WebSocket simulation → Mock map engine: uses fallback behavior (evidence: `backend/src/simulation/ws_frontend_engine.py`)
- Human evaluation → PostgreSQL: stores ratings
- Evaluation pipeline → Case data loader: loads evaluation cases (evidence: `backend/src/eval/eval_pipeline.py`)
- Reflective Skill growth → Legal agent wrappers: creates reflection lawyer (evidence: `backend/gitskill/pipeline.py`)
- Case dataset builder → Model provider: generates profiles and questions (evidence: `dataset_builder/case_dataset_builder/pipeline.py`)
