# alouetter/alavette-form architecture

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

- Interactive diagram: https://gitdiagram.com/alouetter/alavette-form
- Repository: https://github.com/alouetter/alavette-form

## Overview

Alavette Form is a local-first Windows document production workbench. Its main workflow prepares a DOCX and supporting materials, configures a work mode, scene and template, checks risks and completeness, executes formatting, then produces documents and reports for human review. The graph also preserves the assistant’s provider-backed content generation and approved document-job path, plus material-package storage. Some subsystems are represented from README descriptions and indexed references; unsampled implementation details and uncertain links are omitted.

Main entry points: [`src/ui/panels/workbench`](https://github.com/alouetter/alavette-form/tree/main/src/ui/panels/workbench) (Workbench UI), [`src/services/production_execution.py`](https://github.com/alouetter/alavette-form/blob/main/src/services/production_execution.py) (Production Execution), [`main.py`](https://github.com/alouetter/alavette-form/blob/main/main.py) (Application Entry), [`src/assistant/ui/workers.py`](https://github.com/alouetter/alavette-form/blob/main/src/assistant/ui/workers.py) (Assistant UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Document Workbench"]
  node_entry["Application Entry<br/>[main.py]"]
  node_cli["CLI Runner<br/>[cli_runner.py]"]
  node_workbench_ui["Workbench UI"]
  node_scene["Scene Config<br/>[scene.py]"]
  node_template["Template Config<br/>[template.py]"]
end

subgraph group_production["Document Production"]
  node_preflight["Document Preflight"]
  node_session["Execution Session"]
  node_production_runtime["Production Execution"]
  node_pipeline["Formatting Pipeline<br/>[runner.py]"]
  node_paragraph_style["Paragraph Styling<br/>[paragraph_style.py]"]
  node_report["Change Reporting<br/>[report_writer.py]"]
  node_result["DOCX and Reports"]
end

subgraph group_materials["Materials"]
  node_material_domain["Material Packages<br/>[model.py]"]
  node_material_repository[("Material Repository<br/>[repository.py]")]
  node_content_artifacts[("Content Artifacts")]
end

subgraph group_assistant["Assistant"]
  node_assistant_ui["Assistant UI<br/>[workers.py]"]
  node_generation["Content Generation"]
  node_turn_runtime["Provider Turn Runtime<br/>[turn_runner.py]"]
  node_provider_router["Provider Router<br/>[router.py]"]
  node_document_job["Document Job"]
end

node_user(("User"))
node_review(("Human Review"))

node_user -->|"starts"| node_entry
node_entry -->|"dispatches CLI"| node_cli
node_entry -->|"opens GUI"| node_workbench_ui
node_user -->|"prepares document"| node_workbench_ui
node_workbench_ui -->|"selects scene"| node_scene
node_workbench_ui -->|"selects template"| node_template
node_workbench_ui -->|"checks risks"| node_preflight
node_workbench_ui -->|"starts execution"| node_session
node_session -->|"runs request"| node_production_runtime
node_production_runtime -.->|"executes formatting"| node_pipeline
node_pipeline -.->|"applies styles"| node_paragraph_style
node_production_runtime -.->|"writes reports"| node_report
node_production_runtime -->|"produces files"| node_result
node_result -->|"reviewed by"| node_review
node_material_repository -->|"uses domain"| node_material_domain
node_content_artifacts -.->|"stores compiled materials"| node_material_domain
node_assistant_ui -->|"runs generation"| node_generation
node_generation -->|"uses turn runtime"| node_turn_runtime
node_turn_runtime -.->|"routes provider"| node_provider_router
node_assistant_ui -->|"runs document job"| node_document_job
node_document_job -.->|"executes approved plan"| node_production_runtime

click node_entry "https://github.com/alouetter/alavette-form/blob/main/main.py"
click node_cli "https://github.com/alouetter/alavette-form/blob/main/src/cli_runner.py"
click node_workbench_ui "https://github.com/alouetter/alavette-form/tree/main/src/ui/panels/workbench"
click node_scene "https://github.com/alouetter/alavette-form/blob/main/src/config/scene.py"
click node_template "https://github.com/alouetter/alavette-form/blob/main/src/config/template.py"
click node_preflight "https://github.com/alouetter/alavette-form/blob/main/src/config/object_preflight_evidence.py"
click node_session "https://github.com/alouetter/alavette-form/blob/main/src/ui/panels/workbench/execution_session_controller.py"
click node_production_runtime "https://github.com/alouetter/alavette-form/blob/main/src/services/production_execution.py"
click node_pipeline "https://github.com/alouetter/alavette-form/blob/main/src/pipeline/runner.py"
click node_paragraph_style "https://github.com/alouetter/alavette-form/blob/main/src/modules/basic/paragraph_style.py"
click node_report "https://github.com/alouetter/alavette-form/blob/main/src/report_writer.py"
click node_result "https://github.com/alouetter/alavette-form/tree/main/src/services/production_runtime"
click node_material_domain "https://github.com/alouetter/alavette-form/blob/main/src/domain/materials/model.py"
click node_material_repository "https://github.com/alouetter/alavette-form/blob/main/src/infrastructure/materials/repository.py"
click node_content_artifacts "https://github.com/alouetter/alavette-form/blob/main/src/services/material_content/artifact_repository.py"
click node_assistant_ui "https://github.com/alouetter/alavette-form/blob/main/src/assistant/ui/workers.py"
click node_generation "https://github.com/alouetter/alavette-form/blob/main/src/assistant/application/content_generation_service.py"
click node_turn_runtime "https://github.com/alouetter/alavette-form/blob/main/src/assistant/runtime/turn_runner.py"
click node_provider_router "https://github.com/alouetter/alavette-form/blob/main/src/assistant/runtime/providers/router.py"
click node_document_job "https://github.com/alouetter/alavette-form/blob/main/src/assistant/application/document_job_controller.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_entry,node_cli,node_workbench_ui,node_scene,node_template,node_user,node_review toneBlue
class node_preflight,node_session,node_production_runtime,node_pipeline,node_paragraph_style,node_report,node_result toneAmber
class node_material_domain,node_material_repository,node_content_artifacts toneMint
class node_assistant_ui,node_generation,node_turn_runtime,node_provider_router,node_document_job toneRose
```

## Components

### Document Workbench

- [Application Entry](https://github.com/alouetter/alavette-form/blob/main/main.py): `main.py`
- [CLI Runner](https://github.com/alouetter/alavette-form/blob/main/src/cli_runner.py): `src/cli_runner.py`
- [Workbench UI](https://github.com/alouetter/alavette-form/tree/main/src/ui/panels/workbench): `src/ui/panels/workbench`
- [Scene Config](https://github.com/alouetter/alavette-form/blob/main/src/config/scene.py): `src/config/scene.py`
- [Template Config](https://github.com/alouetter/alavette-form/blob/main/src/config/template.py): `src/config/template.py`

### Document Production

- [Document Preflight](https://github.com/alouetter/alavette-form/blob/main/src/config/object_preflight_evidence.py): `src/config/object_preflight_evidence.py`
- [Execution Session](https://github.com/alouetter/alavette-form/blob/main/src/ui/panels/workbench/execution_session_controller.py): `src/ui/panels/workbench/execution_session_controller.py`
- [Production Execution](https://github.com/alouetter/alavette-form/blob/main/src/services/production_execution.py): `src/services/production_execution.py`
- [Formatting Pipeline](https://github.com/alouetter/alavette-form/blob/main/src/pipeline/runner.py): `src/pipeline/runner.py`
- [Paragraph Styling](https://github.com/alouetter/alavette-form/blob/main/src/modules/basic/paragraph_style.py): `src/modules/basic/paragraph_style.py`
- [Change Reporting](https://github.com/alouetter/alavette-form/blob/main/src/report_writer.py): `src/report_writer.py`
- [DOCX and Reports](https://github.com/alouetter/alavette-form/tree/main/src/services/production_runtime): `src/services/production_runtime`

### Materials

- [Material Packages](https://github.com/alouetter/alavette-form/blob/main/src/domain/materials/model.py): `src/domain/materials/model.py`
- [Material Repository](https://github.com/alouetter/alavette-form/blob/main/src/infrastructure/materials/repository.py): `src/infrastructure/materials/repository.py`
- [Content Artifacts](https://github.com/alouetter/alavette-form/blob/main/src/services/material_content/artifact_repository.py): `src/services/material_content/artifact_repository.py`

### Assistant

- [Assistant UI](https://github.com/alouetter/alavette-form/blob/main/src/assistant/ui/workers.py): `src/assistant/ui/workers.py`
- [Content Generation](https://github.com/alouetter/alavette-form/blob/main/src/assistant/application/content_generation_service.py): `src/assistant/application/content_generation_service.py`
- [Provider Turn Runtime](https://github.com/alouetter/alavette-form/blob/main/src/assistant/runtime/turn_runner.py): `src/assistant/runtime/turn_runner.py`
- [Provider Router](https://github.com/alouetter/alavette-form/blob/main/src/assistant/runtime/providers/router.py): `src/assistant/runtime/providers/router.py`
- [Document Job](https://github.com/alouetter/alavette-form/blob/main/src/assistant/application/document_job_controller.py): `src/assistant/application/document_job_controller.py`

### Other components

- **User**
- **Human Review**

## Connections

- User → Application Entry: starts (evidence: `README.md`)
- Application Entry → CLI Runner: dispatches CLI (evidence: `main.py`)
- Application Entry → Workbench UI: opens GUI (evidence: `main.py`)
- User → Workbench UI: prepares document (evidence: `README.md`)
- Workbench UI → Scene Config: selects scene (evidence: `README.md`)
- Workbench UI → Template Config: selects template (evidence: `README.md`)
- Workbench UI → Document Preflight: checks risks (evidence: `README.md`)
- Workbench UI → Execution Session: starts execution (evidence: `src/ui/panels/workbench/execution_session_controller.py`)
- Execution Session → Production Execution: runs request (evidence: `src/ui/panels/workbench/execution_session_controller.py`)
- Production Execution → Formatting Pipeline: executes formatting
- Formatting Pipeline → Paragraph Styling: applies styles
- Production Execution → Change Reporting: writes reports
- Production Execution → DOCX and Reports: produces files (evidence: `README.md`)
- DOCX and Reports → Human Review: reviewed by (evidence: `README.md`)
- Material Repository → Material Packages: uses domain (evidence: `src/infrastructure/materials/repository.py`)
- Content Artifacts → Material Packages: stores compiled materials
- Assistant UI → Content Generation: runs generation (evidence: `src/assistant/ui/workers.py`)
- Content Generation → Provider Turn Runtime: uses turn runtime (evidence: `src/assistant/application/content_generation_service.py`)
- Provider Turn Runtime → Provider Router: routes provider
- Assistant UI → Document Job: runs document job (evidence: `src/assistant/ui/workers.py`)
- Document Job → Production Execution: executes approved plan