# tarequesyed/amp-gen-material-passport architecture

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

- Interactive diagram: https://gitdiagram.com/tarequesyed/amp-gen-material-passport
- Repository: https://github.com/tarequesyed/amp-gen-material-passport

## Overview

AMP-GEN turns a scanned construction Bill of Quantities into a material passport with normalized quantities, material categories, and estimated mass and embodied carbon. The main reproducible workflow uses reviewed BoQ items by default; optional OCR generates candidate text from the scanned PDF. Normalization validates the 64 items, then export writes JSON, fills the Excel template, and creates a summary chart. A Streamlit interface presents passport metrics and analysis, with an optional Ollama-assisted classification path. The dashboard’s full data-loading and editing behavior is not shown in the sampled source, so uncertain wiring is omitted.

Main entry points: [`src/export_outputs.py`](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/export_outputs.py) (Passport export), [`src/pipeline.py`](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/pipeline.py) (Pipeline runner), [`src/normalize.py`](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/normalize.py) (Normalize quantities), [`app.py`](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/app.py) (Passport dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Passport pipeline"]
  node_pipeline_runner["Pipeline runner<br/>[pipeline.py]"]
  node_ocr["BoQ OCR<br/>[extract_boq.py]"]
  node_normalize["Normalize quantities<br/>[normalize.py]"]
  node_export["Passport export<br/>[export_outputs.py]"]
end

subgraph group_classification["Material classification"]
  node_classifier["Rule classifier<br/>[normalize.py]"]
  node_llm_router["Confidence router<br/>[llm_extractor.py]"]
end

subgraph group_dashboard["Interactive dashboard"]
  node_dashboard["Passport dashboard<br/>[app.py]"]
end

subgraph group_artifacts["Inputs and outputs"]
  node_reviewed_items["Reviewed BoQ items"]
  node_source_pdf["Scanned BoQ"]
  node_passport_template["Passport template"]
  node_normalized_items["Normalized records"]
  node_passport_json["Passport JSON<br/>[passport.json]"]
  node_passport_xlsx["Filled passport"]
  node_summary_chart["Summary chart"]
  node_building_meta["Building metadata<br/>[building_meta.json]"]
end

node_user(("Project user"))
node_ollama{{"Ollama service"}}

node_user -->|"runs pipeline"| node_pipeline_runner
node_pipeline_runner -.->|"optionally runs"| node_ocr
node_pipeline_runner -->|"runs"| node_normalize
node_pipeline_runner -->|"runs"| node_export
node_ocr -->|"reads"| node_source_pdf
node_normalize -->|"reads"| node_reviewed_items
node_normalize -->|"writes"| node_normalized_items
node_normalize -->|"classifies with"| node_classifier
node_export -->|"reads"| node_normalized_items
node_export -->|"reads"| node_passport_template
node_export -->|"writes"| node_passport_json
node_export -->|"writes"| node_passport_xlsx
node_export -->|"writes"| node_summary_chart
node_user -->|"views and explores"| node_dashboard
node_dashboard -->|"reads"| node_passport_json
node_dashboard -->|"reads"| node_building_meta
node_dashboard -.->|"classifies with"| node_llm_router
node_llm_router -.->|"requests classification"| node_ollama
node_llm_router -->|"falls back to"| node_classifier

click node_pipeline_runner "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/pipeline.py"
click node_ocr "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/extract_boq.py"
click node_normalize "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/normalize.py"
click node_export "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/export_outputs.py"
click node_classifier "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/normalize.py"
click node_llm_router "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/llm_extractor.py"
click node_dashboard "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/app.py"
click node_reviewed_items "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/data/reviewed_items.json"
click node_source_pdf "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/input/BoQ_CBRI_Principals_Residence.pdf"
click node_passport_template "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/input/AMP_Passport_Template.xlsx"
click node_passport_json "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/output/passport.json"
click node_passport_xlsx "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/output/passport_filled.xlsx"
click node_building_meta "https://github.com/tarequesyed/amp-gen-material-passport/blob/main/output/building_meta.json"

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_pipeline_runner,node_ocr,node_normalize,node_export,node_user toneBlue
class node_classifier,node_llm_router toneAmber
class node_dashboard toneMint
class node_reviewed_items,node_source_pdf,node_passport_template,node_normalized_items,node_passport_json,node_passport_xlsx,node_summary_chart,node_building_meta toneRose
class node_ollama toneIndigo
```

## Components

### Passport pipeline

- [Pipeline runner](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/pipeline.py): `src/pipeline.py`
- [BoQ OCR](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/extract_boq.py): `src/extract_boq.py`
- [Normalize quantities](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/normalize.py): `src/normalize.py`
- [Passport export](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/export_outputs.py): `src/export_outputs.py`

### Material classification

- [Rule classifier](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/normalize.py): `src/normalize.py`
- [Confidence router](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/src/llm_extractor.py): `src/llm_extractor.py`

### Interactive dashboard

- [Passport dashboard](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/app.py): `app.py`

### Inputs and outputs

- [Reviewed BoQ items](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/data/reviewed_items.json): `data/reviewed_items.json`
- [Scanned BoQ](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/input/BoQ_CBRI_Principals_Residence.pdf): `input/BoQ_CBRI_Principals_Residence.pdf`
- [Passport template](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/input/AMP_Passport_Template.xlsx): `input/AMP_Passport_Template.xlsx`
- **Normalized records**
- [Passport JSON](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/output/passport.json): `output/passport.json`
- [Filled passport](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/output/passport_filled.xlsx): `output/passport_filled.xlsx`
- **Summary chart**
- [Building metadata](https://github.com/tarequesyed/amp-gen-material-passport/blob/main/output/building_meta.json): `output/building_meta.json`

### Other components

- **Project user**
- **Ollama service**

## Connections

- Project user → Pipeline runner: runs pipeline
- Pipeline runner → BoQ OCR: optionally runs
- Pipeline runner → Normalize quantities: runs
- Pipeline runner → Passport export: runs
- BoQ OCR → Scanned BoQ: reads
- Normalize quantities → Reviewed BoQ items: reads
- Normalize quantities → Normalized records: writes
- Normalize quantities → Rule classifier: classifies with
- Passport export → Normalized records: reads
- Passport export → Passport template: reads
- Passport export → Passport JSON: writes
- Passport export → Filled passport: writes
- Passport export → Summary chart: writes
- Project user → Passport dashboard: views and explores
- Passport dashboard → Passport JSON: reads
- Passport dashboard → Building metadata: reads
- Passport dashboard → Confidence router: classifies with
- Confidence router → Ollama service: requests classification
- Confidence router → Rule classifier: falls back to