# echo-smith/luminwrite-oss architecture

> Architecture diagram of the GitHub repository echo-smith/luminwrite-oss, 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/echo-smith/luminwrite-oss
- Repository: https://github.com/echo-smith/luminwrite-oss

## Overview

LuminWrite is a self-hosted Chinese-language AI writing workbench. A creator supplies a request and materials in the React app; the Go API runs a governed workflow from contract and executable plan through research or retrieval, drafting, and quality gates, then returns artifacts and run events for review. PostgreSQL-backed stores preserve documents, run state, evidence, and memory. The README also documents profile/style management, long-term memory, and WABench/red-team evaluation as major product branches. Runtime wiring is inferred only where the README or sampled source supports it; unsampled subsystem links are omitted where uncertain.

Main entry points: [`backend/internal/writingruntime/executor.go`](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/executor.go) (Plan executor), [`backend/internal/database/postgres.go`](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/database/postgres.go) (PostgreSQL), [`backend/internal/writingruntime/orchestrator.go`](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/orchestrator.go) (Runtime orchestrator), [`backend/internal/server/writing_api.go`](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/writing_api.go) (Writing handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Writing experience"]
  node_workbench["React workbench<br/>[App.tsx]"]
  node_writing_ui["Writing composer"]
  node_writing_api["Writing API<br/>[writing-api.ts]"]
  node_api_server["Go API server<br/>[server.go]"]
  node_writing_handlers["Writing handlers<br/>[writing_api.go]"]
end

subgraph group_governance["Governed writing"]
  node_runtime["Runtime orchestrator<br/>[orchestrator.go]"]
  node_contract["Writing contract<br/>[contract.go]"]
  node_plan["Plan compiler<br/>[compiler.go]"]
  node_executor["Plan executor<br/>[executor.go]"]
  node_quality["Quality gates<br/>[gates.go]"]
  node_research["Research workflow"]
end

subgraph group_capabilities["Shared capabilities"]
  node_scholar["Academic research<br/>[client.go]"]
  node_knowledge["Knowledge retrieval<br/>[kb_manager.go]"]
  node_memory["Layered memory<br/>[service.go]"]
  node_profile["Style profiles<br/>[profile.go]"]
  node_llm["LLM client factory<br/>[llm_service.go]"]
end

subgraph group_persistence["Persistence"]
  node_writing_store["Writing store<br/>[store.go]"]
  node_postgres[("PostgreSQL<br/>[postgres.go]")]
end

subgraph group_operations["Evaluation and administration"]
  node_evaluation["WABench evaluation"]
  node_admin["Admin services<br/>[handlers_admin.go]"]
end

node_creator(("Creator"))
node_docreader["Document parser"]
node_model_provider["Model provider"]

node_creator -->|"uses"| node_workbench
node_workbench -->|"opens"| node_writing_ui
node_writing_ui -->|"submits request"| node_writing_api
node_writing_api -->|"REST commands"| node_writing_handlers
node_writing_handlers -->|"starts runs"| node_runtime
node_runtime -->|"validates contract"| node_contract
node_runtime -->|"compiles plan"| node_plan
node_runtime -->|"dispatches execution"| node_executor
node_executor -->|"runs gates"| node_quality
node_executor -->|"dispatches research"| node_research
node_research -->|"fetches and reads"| node_scholar
node_scholar -.->|"parses documents"| node_docreader
node_executor -->|"retrieves materials"| node_knowledge
node_executor -->|"uses memory"| node_memory
node_executor -->|"resolves style"| node_profile
node_executor -->|"requests generation"| node_llm
node_llm -->|"calls model API"| node_model_provider
node_runtime -->|"persists run state"| node_writing_store
node_writing_store -->|"reads and writes"| node_postgres
node_knowledge -->|"indexes and searches"| node_postgres
node_memory -->|"stores memory"| node_postgres
node_profile -->|"loads profiles"| node_postgres
node_writing_handlers -->|"streams run events"| node_writing_api
node_creator -->|"reviews candidates"| node_evaluation
node_evaluation -->|"stores evaluations"| node_postgres
node_admin -->|"manages configuration"| node_postgres

click node_workbench "https://github.com/echo-smith/luminwrite-oss/blob/main/frontend/src/App.tsx"
click node_writing_ui "https://github.com/echo-smith/luminwrite-oss/blob/main/frontend/src/components/composer/writing-composer.tsx"
click node_writing_api "https://github.com/echo-smith/luminwrite-oss/blob/main/frontend/src/lib/writing-api.ts"
click node_api_server "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/server.go"
click node_writing_handlers "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/writing_api.go"
click node_runtime "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/orchestrator.go"
click node_contract "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingkernel/contract.go"
click node_plan "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingplan/compiler.go"
click node_executor "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/executor.go"
click node_quality "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingquality/gates.go"
click node_research "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/research_discover.go"
click node_scholar "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/scholar/client.go"
click node_knowledge "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/services/kb_manager.go"
click node_memory "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/memory/service.go"
click node_profile "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/profile/profile.go"
click node_llm "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/services/llm_service.go"
click node_writing_store "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingstore/store.go"
click node_postgres "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/database/postgres.go"
click node_evaluation "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/services/wabench_evaluation.go"
click node_admin "https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/handlers_admin.go"

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_workbench,node_writing_ui,node_writing_api,node_api_server,node_writing_handlers toneBlue
class node_runtime,node_contract,node_plan,node_executor,node_quality,node_research toneAmber
class node_scholar,node_knowledge,node_memory,node_profile,node_llm toneMint
class node_writing_store,node_postgres toneRose
class node_evaluation,node_admin,node_creator,node_docreader,node_model_provider toneIndigo
```

## Components

### Writing experience

- [React workbench](https://github.com/echo-smith/luminwrite-oss/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Writing composer](https://github.com/echo-smith/luminwrite-oss/blob/main/frontend/src/components/composer/writing-composer.tsx): `frontend/src/components/composer/writing-composer.tsx`
- [Writing API](https://github.com/echo-smith/luminwrite-oss/blob/main/frontend/src/lib/writing-api.ts): `frontend/src/lib/writing-api.ts`
- [Go API server](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/server.go): `backend/internal/server/server.go`
- [Writing handlers](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/writing_api.go): `backend/internal/server/writing_api.go`

### Governed writing

- [Runtime orchestrator](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/orchestrator.go): `backend/internal/writingruntime/orchestrator.go`
- [Writing contract](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingkernel/contract.go): `backend/internal/writingkernel/contract.go`
- [Plan compiler](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingplan/compiler.go): `backend/internal/writingplan/compiler.go`
- [Plan executor](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/executor.go): `backend/internal/writingruntime/executor.go`
- [Quality gates](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingquality/gates.go): `backend/internal/writingquality/gates.go`
- [Research workflow](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingruntime/research_discover.go): `backend/internal/writingruntime/research_discover.go`

### Shared capabilities

- [Academic research](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/scholar/client.go): `backend/internal/scholar/client.go`
- [Knowledge retrieval](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/services/kb_manager.go): `backend/internal/services/kb_manager.go`
- [Layered memory](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/memory/service.go): `backend/internal/memory/service.go`
- [Style profiles](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/profile/profile.go): `backend/internal/profile/profile.go`
- [LLM client factory](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/services/llm_service.go): `backend/internal/services/llm_service.go`

### Persistence

- [Writing store](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/writingstore/store.go): `backend/internal/writingstore/store.go`
- [PostgreSQL](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/database/postgres.go): `backend/internal/database/postgres.go`

### Evaluation and administration

- [WABench evaluation](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/services/wabench_evaluation.go): `backend/internal/services/wabench_evaluation.go`
- [Admin services](https://github.com/echo-smith/luminwrite-oss/blob/main/backend/internal/server/handlers_admin.go): `backend/internal/server/handlers_admin.go`

### Other components

- **Creator**
- **Document parser**
- **Model provider**

## Connections

- Creator → React workbench: uses
- React workbench → Writing composer: opens
- Writing composer → Writing API: submits request
- Writing API → Writing handlers: REST commands
- Writing handlers → Runtime orchestrator: starts runs
- Runtime orchestrator → Writing contract: validates contract
- Runtime orchestrator → Plan compiler: compiles plan
- Runtime orchestrator → Plan executor: dispatches execution
- Plan executor → Quality gates: runs gates
- Plan executor → Research workflow: dispatches research
- Research workflow → Academic research: fetches and reads
- Academic research → Document parser: parses documents
- Plan executor → Knowledge retrieval: retrieves materials
- Plan executor → Layered memory: uses memory
- Plan executor → Style profiles: resolves style
- Plan executor → LLM client factory: requests generation
- LLM client factory → Model provider: calls model API
- Runtime orchestrator → Writing store: persists run state
- Writing store → PostgreSQL: reads and writes
- Knowledge retrieval → PostgreSQL: indexes and searches
- Layered memory → PostgreSQL: stores memory
- Style profiles → PostgreSQL: loads profiles
- Writing handlers → Writing API: streams run events
- Creator → WABench evaluation: reviews candidates
- WABench evaluation → PostgreSQL: stores evaluations
- Admin services → PostgreSQL: manages configuration