# sudo-kno3/esa-suite architecture

> Architecture diagram of the GitHub repository sudo-kno3/esa-suite, 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/sudo-kno3/esa-suite
- Repository: https://github.com/sudo-kno3/esa-suite

## Overview

esa-suite automates Phase I Environmental Site Assessment reports, from evidence collection through a reviewable Word draft. The principal workflow gathers source documents and field observations, parses and reconciles evidence, derives controlled findings, assembles and validates report sections, then delivers a draft for qualified-person review. Standalone chapter tools cover ERIS records, title searches, and physical setting; the Android field-form app supplies site observations. The editor applies tracked changes after draft generation. The graph follows the README’s product map and sampled implementation seams; several subsystem links reflect documented capabilities rather than inspected call sites.

Main entry points: [`report-engine/src/pipeline/mod.rs`](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/mod.rs) (Assessment pipeline), [`report-engine/src/reporting/report.rs`](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/report.rs) (Report assembly), [`report-engine/src/pipeline/evidence/mod.rs`](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/evidence/mod.rs) (Evidence assembly), [`editing/src/app.rs`](https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/app.rs) (Technical editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Evidence capture"]
  node_field_app["Field-form app<br/>[MainActivity.kt]"]
  node_field_export["Field JSON export<br/>[PackageWriter.kt]"]
end

subgraph group_engine["Report engine"]
  node_ingestion["Document ingestion<br/>[mod.rs]"]
  node_section_engines["Section engines<br/>[engines.rs]"]
  node_evidence["Evidence assembly<br/>[mod.rs]"]
  node_pipeline["Assessment pipeline<br/>[mod.rs]"]
  node_claims["Claims and findings<br/>[mod.rs]"]
  node_fact_graph["Fact graph<br/>[mod.rs]"]
  node_ai_flow["AI prose pass<br/>[pipeline.rs]"]
  node_reporting["Report assembly<br/>[report.rs]"]
  node_report_sections["Report sections<br/>[mod.rs]"]
  node_release_gate["Release validation<br/>[mod.rs]"]
  node_delivery["Report delivery<br/>[deliver.rs]"]
end

subgraph group_draft["Draft and review"]
  node_word_draft["Word draft<br/>[output.rs]"]
  node_editor["Technical editor<br/>[app.rs]"]
  node_rule_engine["Style rules<br/>[engine.rs]"]
  node_tracked_changes["Tracked changes<br/>[redline.rs]"]
end

subgraph group_chapter["Chapter tools"]
  node_chapter_tools["Standalone chapters<br/>[engine.rs]"]
end

node_assessor(("Assessor"))
node_documents["Source documents"]
node_qp(("Qualified person"))

node_assessor -->|"provides"| node_documents
node_assessor -->|"records observations"| node_field_app
node_field_app -->|"exports package"| node_field_export
node_documents -->|"parses inputs"| node_ingestion
node_field_export -->|"supplies field data"| node_evidence
node_documents -.->|"runs chapter extraction"| node_section_engines
node_chapter_tools -.->|"produces chapter data"| node_section_engines
node_ingestion -->|"extracts evidence"| node_evidence
node_section_engines -->|"returns JSON"| node_evidence
node_evidence -->|"feeds assessment"| node_pipeline
node_pipeline -->|"derives findings"| node_claims
node_pipeline -->|"builds fact graph"| node_fact_graph
node_pipeline -->|"assembles report"| node_reporting
node_claims -->|"informs rendering"| node_report_sections
node_fact_graph -->|"provides fact context"| node_ai_flow
node_ai_flow -->|"refines prose"| node_reporting
node_reporting -->|"renders sections"| node_report_sections
node_reporting -->|"validates draft"| node_release_gate
node_release_gate -->|"permits delivery"| node_delivery
node_delivery -->|"writes DOCX"| node_word_draft
node_word_draft -->|"opens for editing"| node_editor
node_editor -->|"reviews prose"| node_rule_engine
node_editor -->|"writes redlines"| node_tracked_changes
node_tracked_changes -->|"presents for review"| node_qp

click node_field_app "https://github.com/sudo-kno3/esa-suite/blob/main/audit/source/field-form-app/app-kotlin/com/azimuth/fieldapp/MainActivity.kt"
click node_field_export "https://github.com/sudo-kno3/esa-suite/blob/main/audit/source/field-form-app/core/data/main/kotlin/com/azimuth/fieldapp/data/export/PackageWriter.kt"
click node_chapter_tools "https://github.com/sudo-kno3/esa-suite/blob/main/sections/3.8-physical-setting/src/engine.rs"
click node_ingestion "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/ingestion/mod.rs"
click node_section_engines "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/ingestion/engines.rs"
click node_evidence "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/evidence/mod.rs"
click node_pipeline "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/mod.rs"
click node_claims "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/claims/mod.rs"
click node_fact_graph "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/graph/mod.rs"
click node_ai_flow "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/ai/pipeline.rs"
click node_reporting "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/report.rs"
click node_report_sections "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/sections/mod.rs"
click node_release_gate "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/gate/mod.rs"
click node_delivery "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/deliver.rs"
click node_word_draft "https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/output.rs"
click node_editor "https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/app.rs"
click node_rule_engine "https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/rules/engine.rs"
click node_tracked_changes "https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/docx/redline.rs"

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_field_app,node_field_export toneBlue
class node_ingestion,node_section_engines,node_evidence,node_pipeline,node_claims,node_fact_graph,node_ai_flow,node_reporting,node_report_sections,node_release_gate,node_delivery toneAmber
class node_word_draft,node_editor,node_rule_engine,node_tracked_changes toneMint
class node_chapter_tools toneRose
class node_assessor,node_documents,node_qp toneIndigo
```

## Components

### Evidence capture

- [Field-form app](https://github.com/sudo-kno3/esa-suite/blob/main/audit/source/field-form-app/app-kotlin/com/azimuth/fieldapp/MainActivity.kt): `audit/source/field-form-app/app-kotlin/com/azimuth/fieldapp/MainActivity.kt`
- [Field JSON export](https://github.com/sudo-kno3/esa-suite/blob/main/audit/source/field-form-app/core/data/main/kotlin/com/azimuth/fieldapp/data/export/PackageWriter.kt): `audit/source/field-form-app/core/data/main/kotlin/com/azimuth/fieldapp/data/export/PackageWriter.kt`

### Report engine

- [Document ingestion](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/ingestion/mod.rs): `report-engine/src/ingestion/mod.rs`
- [Section engines](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/ingestion/engines.rs): `report-engine/src/ingestion/engines.rs`
- [Evidence assembly](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/evidence/mod.rs): `report-engine/src/pipeline/evidence/mod.rs`
- [Assessment pipeline](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/mod.rs): `report-engine/src/pipeline/mod.rs`
- [Claims and findings](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/claims/mod.rs): `report-engine/src/claims/mod.rs`
- [Fact graph](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/graph/mod.rs): `report-engine/src/graph/mod.rs`
- [AI prose pass](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/ai/pipeline.rs): `report-engine/src/ai/pipeline.rs`
- [Report assembly](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/report.rs): `report-engine/src/reporting/report.rs`
- [Report sections](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/sections/mod.rs): `report-engine/src/reporting/sections/mod.rs`
- [Release validation](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/gate/mod.rs): `report-engine/src/reporting/gate/mod.rs`
- [Report delivery](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/pipeline/deliver.rs): `report-engine/src/pipeline/deliver.rs`

### Draft and review

- [Word draft](https://github.com/sudo-kno3/esa-suite/blob/main/report-engine/src/reporting/output.rs): `report-engine/src/reporting/output.rs`
- [Technical editor](https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/app.rs): `editing/src/app.rs`
- [Style rules](https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/rules/engine.rs): `editing/src/rules/engine.rs`
- [Tracked changes](https://github.com/sudo-kno3/esa-suite/blob/main/editing/src/docx/redline.rs): `editing/src/docx/redline.rs`

### Chapter tools

- [Standalone chapters](https://github.com/sudo-kno3/esa-suite/blob/main/sections/3.8-physical-setting/src/engine.rs): `sections/3.8-physical-setting/src/engine.rs`

### Other components

- **Assessor**
- **Source documents**
- **Qualified person**

## Connections

- Assessor → Source documents: provides
- Assessor → Field-form app: records observations
- Field-form app → Field JSON export: exports package
- Source documents → Document ingestion: parses inputs
- Field JSON export → Evidence assembly: supplies field data
- Source documents → Section engines: runs chapter extraction
- Standalone chapters → Section engines: produces chapter data
- Document ingestion → Evidence assembly: extracts evidence
- Section engines → Evidence assembly: returns JSON
- Evidence assembly → Assessment pipeline: feeds assessment
- Assessment pipeline → Claims and findings: derives findings
- Assessment pipeline → Fact graph: builds fact graph
- Assessment pipeline → Report assembly: assembles report
- Claims and findings → Report sections: informs rendering
- Fact graph → AI prose pass: provides fact context
- AI prose pass → Report assembly: refines prose
- Report assembly → Report sections: renders sections
- Report assembly → Release validation: validates draft
- Release validation → Report delivery: permits delivery
- Report delivery → Word draft: writes DOCX
- Word draft → Technical editor: opens for editing
- Technical editor → Style rules: reviews prose
- Technical editor → Tracked changes: writes redlines
- Tracked changes → Qualified person: presents for review