# hill-1024/lawyance architecture

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

- Interactive diagram: https://gitdiagram.com/hill-1024/lawyance
- Repository: https://github.com/hill-1024/lawyance

## Overview

Lawver is a Chinese-language legal AI assistant. A user chats or starts a simulated-court session in the React app; requests reach FastAPI routes and service pipelines, which assemble context and run agents. Agents use business tools through the shared MCP forwarding layer to retrieve legal and company information, process documents, search the web, and access conversation memory. The frontend also manages conversation workspaces and local records. The README documents these boundaries; unsampled source leaves some internal calls and provider wiring unverified.

Main entry points: [`routes`](https://github.com/hill-1024/lawyance/tree/main/routes) (HTTP routes), [`services/court_pipeline.py`](https://github.com/hill-1024/lawyance/blob/main/services/court_pipeline.py) (Court pipeline), [`mcps.py`](https://github.com/hill-1024/lawyance/blob/main/mcps.py) (Tool forwarding), [`services/chat_pipeline.py`](https://github.com/hill-1024/lawyance/blob/main/services/chat_pipeline.py) (Chat pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User application"]
  node_app["Application shell<br/>[App.tsx]"]
  node_chat_ui["Chat workflow<br/>[useChat.ts]"]
  node_court_ui["Court workflow<br/>[CourtPage.tsx]"]
  node_local_store[("Local storage<br/>[db.ts]")]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_backend["Request handling"]
  node_fastapi["Application factory<br/>[app_factory.py]"]
  node_routes["HTTP routes"]
  node_chat_pipeline["Chat pipeline<br/>[chat_pipeline.py]"]
  node_court_pipeline["Court pipeline<br/>[court_pipeline.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_reasoning["Agent and review"]
  node_agent_builder["Agent builder<br/>[agent_builder.py]"]
  node_tool_loop["Agent tool loop<br/>[tool_loop.py]"]
  node_ocp["Output review<br/>[ocp_service.py]"]
end

subgraph group_capabilities["Legal capabilities"]
  node_tool_router["Tool forwarding<br/>[mcps.py]"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
  node_legal_search["Legal data search<br/>[law_data_search.py]"]
  node_mcp_clients["MCP clients"]
end

subgraph group_state["Memory and workspace"]
  node_memory[("Conversation memory")]
  node_workspace["Session workspace<br/>[workspace.py]"]
end

node_user(("User"))
node_model["Model service"]
node_data_sources["Legal and company sources"]

node_user -->|"uses"| node_app
node_app -->|"presents"| node_chat_ui
node_app -->|"routes to"| node_court_ui
node_chat_ui -->|"sends chat"| node_api
node_court_ui -->|"sends turns"| node_api
node_chat_ui -->|"persists conversations"| node_local_store
node_api -->|"calls REST/stream"| node_routes
node_routes -->|"registered in"| node_fastapi
node_routes -->|"uses authentication"| node_auth
node_routes -->|"forwards chat"| node_chat_pipeline
node_routes -->|"forwards court turns"| node_court_pipeline
node_chat_pipeline -->|"builds agent"| node_agent_builder
node_court_pipeline -->|"runs agent"| node_tool_loop
node_agent_builder -->|"selects agent"| node_tool_loop
node_agent_builder -->|"builds review"| node_ocp
node_tool_loop -.->|"requests completion"| node_model
node_tool_loop -->|"dispatches tools"| node_tool_router
node_court_pipeline -->|"dispatches court tools"| node_tool_router
node_tool_router -->|"uses registry"| node_tool_registry
node_tool_router -->|"forwards calls"| node_mcp_clients
node_mcp_clients -.->|"queries local law"| node_legal_search
node_legal_search -.->|"searches"| node_data_sources
node_mcp_clients -.->|"queries legal/company"| node_data_sources
node_chat_pipeline -->|"syncs and retrieves"| node_memory
node_court_pipeline -->|"syncs role memory"| node_memory
node_chat_pipeline -->|"scopes session"| node_workspace
node_court_pipeline -->|"scopes session"| node_workspace
node_tool_router -->|"validates paths"| node_workspace

click node_app "https://github.com/hill-1024/lawyance/blob/main/src/App.tsx"
click node_chat_ui "https://github.com/hill-1024/lawyance/blob/main/src/hooks/useChat.ts"
click node_court_ui "https://github.com/hill-1024/lawyance/blob/main/src/components/CourtPage.tsx"
click node_local_store "https://github.com/hill-1024/lawyance/blob/main/src/lib/db.ts"
click node_api "https://github.com/hill-1024/lawyance/blob/main/src/services/api.ts"
click node_fastapi "https://github.com/hill-1024/lawyance/blob/main/app_factory.py"
click node_routes "https://github.com/hill-1024/lawyance/tree/main/routes"
click node_chat_pipeline "https://github.com/hill-1024/lawyance/blob/main/services/chat_pipeline.py"
click node_court_pipeline "https://github.com/hill-1024/lawyance/blob/main/services/court_pipeline.py"
click node_auth "https://github.com/hill-1024/lawyance/blob/main/auth.py"
click node_agent_builder "https://github.com/hill-1024/lawyance/blob/main/services/agent_builder.py"
click node_tool_loop "https://github.com/hill-1024/lawyance/blob/main/agents/tool_loop.py"
click node_ocp "https://github.com/hill-1024/lawyance/blob/main/services/ocp_service.py"
click node_tool_router "https://github.com/hill-1024/lawyance/blob/main/mcps.py"
click node_tool_registry "https://github.com/hill-1024/lawyance/blob/main/tools/registry.py"
click node_legal_search "https://github.com/hill-1024/lawyance/blob/main/RAG/law_data_search.py"
click node_mcp_clients "https://github.com/hill-1024/lawyance/tree/main/mcp"
click node_memory "https://github.com/hill-1024/lawyance/tree/main/memory_system/service"
click node_workspace "https://github.com/hill-1024/lawyance/blob/main/workspace.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_chat_ui,node_court_ui,node_local_store,node_api,node_user toneBlue
class node_fastapi,node_routes,node_chat_pipeline,node_court_pipeline,node_auth toneAmber
class node_agent_builder,node_tool_loop,node_ocp toneMint
class node_tool_router,node_tool_registry,node_legal_search,node_mcp_clients toneRose
class node_memory,node_workspace,node_model,node_data_sources toneIndigo
```

## Components

### User application

- [Application shell](https://github.com/hill-1024/lawyance/blob/main/src/App.tsx): `src/App.tsx`
- [Chat workflow](https://github.com/hill-1024/lawyance/blob/main/src/hooks/useChat.ts): `src/hooks/useChat.ts`
- [Court workflow](https://github.com/hill-1024/lawyance/blob/main/src/components/CourtPage.tsx): `src/components/CourtPage.tsx`
- [Local storage](https://github.com/hill-1024/lawyance/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [API client](https://github.com/hill-1024/lawyance/blob/main/src/services/api.ts): `src/services/api.ts`

### Request handling

- [Application factory](https://github.com/hill-1024/lawyance/blob/main/app_factory.py): `app_factory.py`
- [HTTP routes](https://github.com/hill-1024/lawyance/tree/main/routes): `routes`
- [Chat pipeline](https://github.com/hill-1024/lawyance/blob/main/services/chat_pipeline.py): `services/chat_pipeline.py`
- [Court pipeline](https://github.com/hill-1024/lawyance/blob/main/services/court_pipeline.py): `services/court_pipeline.py`
- [Authentication](https://github.com/hill-1024/lawyance/blob/main/auth.py): `auth.py`

### Agent and review

- [Agent builder](https://github.com/hill-1024/lawyance/blob/main/services/agent_builder.py): `services/agent_builder.py`
- [Agent tool loop](https://github.com/hill-1024/lawyance/blob/main/agents/tool_loop.py): `agents/tool_loop.py`
- [Output review](https://github.com/hill-1024/lawyance/blob/main/services/ocp_service.py): `services/ocp_service.py`

### Legal capabilities

- [Tool forwarding](https://github.com/hill-1024/lawyance/blob/main/mcps.py): `mcps.py`
- [Tool registry](https://github.com/hill-1024/lawyance/blob/main/tools/registry.py): `tools/registry.py`
- [Legal data search](https://github.com/hill-1024/lawyance/blob/main/RAG/law_data_search.py): `RAG/law_data_search.py`
- [MCP clients](https://github.com/hill-1024/lawyance/tree/main/mcp): `mcp`

### Memory and workspace

- [Conversation memory](https://github.com/hill-1024/lawyance/tree/main/memory_system/service): `memory_system/service`
- [Session workspace](https://github.com/hill-1024/lawyance/blob/main/workspace.py): `workspace.py`

### Other components

- **User**
- **Model service**
- **Legal and company sources**

## Connections

- User → Application shell: uses (evidence: `README.md`)
- Application shell → Chat workflow: presents (evidence: `src/App.tsx`)
- Application shell → Court workflow: routes to (evidence: `src/App.tsx`)
- Chat workflow → API client: sends chat (evidence: `src/hooks/useChat.ts`)
- Court workflow → API client: sends turns (evidence: `README.md`)
- Chat workflow → Local storage: persists conversations (evidence: `src/hooks/useChat.ts`)
- API client → HTTP routes: calls REST/stream (evidence: `README.md`)
- HTTP routes → Application factory: registered in (evidence: `README.md`)
- HTTP routes → Authentication: uses authentication (evidence: `routes/auth.py`)
- HTTP routes → Chat pipeline: forwards chat (evidence: `README.md`)
- HTTP routes → Court pipeline: forwards court turns (evidence: `README.md`)
- Chat pipeline → Agent builder: builds agent (evidence: `services/chat_pipeline.py`)
- Court pipeline → Agent tool loop: runs agent (evidence: `services/court_pipeline.py`)
- Agent builder → Agent tool loop: selects agent (evidence: `README.md`)
- Agent builder → Output review: builds review (evidence: `README.md`)
- Agent tool loop → Model service: requests completion
- Agent tool loop → Tool forwarding: dispatches tools (evidence: `README.md`)
- Court pipeline → Tool forwarding: dispatches court tools (evidence: `README.md`)
- Tool forwarding → Tool registry: uses registry (evidence: `mcps.py`)
- Tool forwarding → MCP clients: forwards calls (evidence: `README.md`)
- MCP clients → Legal data search: queries local law
- Legal data search → Legal and company sources: searches
- MCP clients → Legal and company sources: queries legal/company
- Chat pipeline → Conversation memory: syncs and retrieves (evidence: `README.md`)
- Court pipeline → Conversation memory: syncs role memory (evidence: `services/court_pipeline.py`)
- Chat pipeline → Session workspace: scopes session (evidence: `README.md`)
- Court pipeline → Session workspace: scopes session (evidence: `README.md`)
- Tool forwarding → Session workspace: validates paths (evidence: `README.md`)