# zhengtat/final-year-project architecture

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

- Interactive diagram: https://gitdiagram.com/zhengtat/final-year-project
- Repository: https://github.com/zhengtat/final-year-project

## Overview

CUMAP builds an expert knowledge graph from textbook material, extracts student-answer graphs, and compares them to diagnose correct, incomplete, or contradictory understanding. The README documents data preparation, gold annotation, evaluation, and review/demo capabilities as additional branches. Sampled pipeline and LLM code supports the expert-graph stages and shared model-call layer; student extraction and diagnosis internals were not sampled, so those components and their links are represented only at the documented subsystem level.

Main entry points: [`src/cumap/cli.py`](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/cli.py) (CLI workflows), [`src/cumap/expert_kg/pipeline.py`](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/pipeline.py) (Expert KG pipeline), [`src/cumap/gold/suggest_expert.py`](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/gold/suggest_expert.py) (Gold annotation tools), [`src/cumap/llm/client.py`](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/llm/client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Corpus preparation"]
  node_data["Dataset preparation"]
  node_textbook_fetch["Textbook fetch<br/>[fetch.py]"]
  node_textbook_parse["Textbook parsing<br/>[parse.py]"]
  node_coverage["Textbook coverage<br/>[coverage.py]"]
end

subgraph group_knowledge["Knowledge graphs"]
  node_expert_pipeline["Expert KG pipeline<br/>[pipeline.py]"]
  node_canonicalize["Concept canonicalization<br/>[canonicalize.py]"]
  node_expert_relations["Relation extraction<br/>[relations.py]"]
  node_kg_snapshots[("KG snapshots<br/>[snapshots.py]")]
end

subgraph group_diagnosis["Student diagnosis"]
  node_student_graph["Student graph extraction"]
  node_diagnosis["Graph diagnosis<br/>[diagnosis.py]"]
  node_relation_registry["Relation registry<br/>[relations.py]"]
end

subgraph group_platform["Shared platform"]
  node_schemas["Graph schemas<br/>[edges.py]"]
  node_llm["LLM client<br/>[client.py]"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_settings["Configuration<br/>[config.py]"]
end

subgraph group_review["Review and evaluation"]
  node_gold_tools["Gold annotation tools<br/>[suggest_expert.py]"]
  node_gold_validation["Gold validation<br/>[validate.py]"]
  node_evaluation["Evaluation"]
  node_report["Reports and visualization<br/>[build.py]"]
  node_gold_editor["Gold review app<br/>[gold_editor.py]"]
end

node_user(("Engineer / educator"))
node_cli["CLI workflows<br/>[cli.py]"]

node_user -->|"runs commands"| node_cli
node_cli -->|"prepares datasets"| node_data
node_cli -->|"fetches source"| node_textbook_fetch
node_cli -->|"parses sections"| node_textbook_parse
node_cli -->|"checks coverage"| node_coverage
node_textbook_fetch -.->|"provides source"| node_textbook_parse
node_cli -.->|"builds expert graph"| node_expert_pipeline
node_expert_pipeline -->|"canonicalizes mentions"| node_canonicalize
node_expert_pipeline -->|"resolves relations"| node_expert_relations
node_expert_pipeline -->|"creates snapshots"| node_kg_snapshots
node_cli -.->|"extracts answer graph"| node_student_graph
node_student_graph -.->|"supplies student graph"| node_diagnosis
node_expert_pipeline -.->|"supplies expert graph"| node_diagnosis
node_diagnosis -.->|"aligns relations"| node_relation_registry
node_cli -->|"suggests annotations"| node_gold_tools
node_gold_tools -->|"requests suggestions"| node_llm
node_gold_tools -->|"verifies quotes"| node_gold_validation
node_cli -->|"validates gold"| node_gold_validation
node_cli -.->|"runs evaluation"| node_evaluation
node_cli -->|"builds demo reports"| node_report
node_report -->|"loads snapshots"| node_kg_snapshots
node_user -.->|"reviews annotations"| node_gold_editor
node_gold_editor -->|"validates edits"| node_gold_validation
node_gold_tools -->|"constructs graph records"| node_schemas
node_llm -->|"reads settings"| node_settings
node_gold_tools -->|"renders prompts"| node_prompts
node_llm -.->|"uses templates"| node_prompts

click node_cli "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/cli.py"
click node_data "https://github.com/zhengtat/final-year-project/tree/master/src/cumap/data"
click node_textbook_fetch "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/textbook/fetch.py"
click node_textbook_parse "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/textbook/parse.py"
click node_coverage "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/textbook/coverage.py"
click node_expert_pipeline "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/pipeline.py"
click node_canonicalize "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/canonicalize.py"
click node_expert_relations "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/relations.py"
click node_kg_snapshots "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/snapshots.py"
click node_student_graph "https://github.com/zhengtat/final-year-project/tree/master/src/cumap"
click node_diagnosis "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/schemas/diagnosis.py"
click node_relation_registry "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/schemas/relations.py"
click node_gold_tools "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/gold/suggest_expert.py"
click node_gold_validation "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/gold/validate.py"
click node_evaluation "https://github.com/zhengtat/final-year-project/tree/master/src/cumap/eval"
click node_report "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/report/build.py"
click node_gold_editor "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/app/gold_editor.py"
click node_schemas "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/schemas/edges.py"
click node_llm "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/llm/client.py"
click node_prompts "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/llm/prompts.py"
click node_settings "https://github.com/zhengtat/final-year-project/blob/master/src/cumap/config.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_data,node_textbook_fetch,node_textbook_parse,node_coverage toneBlue
class node_expert_pipeline,node_canonicalize,node_expert_relations,node_kg_snapshots toneAmber
class node_student_graph,node_diagnosis,node_relation_registry toneMint
class node_schemas,node_llm,node_prompts,node_settings toneRose
class node_gold_tools,node_gold_validation,node_evaluation,node_report,node_gold_editor,node_user toneIndigo
class node_cli toneTeal
```

## Components

### Corpus preparation

- [Dataset preparation](https://github.com/zhengtat/final-year-project/tree/master/src/cumap/data): `src/cumap/data`
- [Textbook fetch](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/textbook/fetch.py): `src/cumap/textbook/fetch.py`
- [Textbook parsing](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/textbook/parse.py): `src/cumap/textbook/parse.py`
- [Textbook coverage](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/textbook/coverage.py): `src/cumap/textbook/coverage.py`

### Knowledge graphs

- [Expert KG pipeline](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/pipeline.py): `src/cumap/expert_kg/pipeline.py`
- [Concept canonicalization](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/canonicalize.py): `src/cumap/expert_kg/canonicalize.py`
- [Relation extraction](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/relations.py): `src/cumap/expert_kg/relations.py`
- [KG snapshots](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/expert_kg/snapshots.py): `src/cumap/expert_kg/snapshots.py`

### Student diagnosis

- [Student graph extraction](https://github.com/zhengtat/final-year-project/tree/master/src/cumap): `src/cumap`
- [Graph diagnosis](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/schemas/diagnosis.py): `src/cumap/schemas/diagnosis.py`
- [Relation registry](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/schemas/relations.py): `src/cumap/schemas/relations.py`

### Shared platform

- [Graph schemas](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/schemas/edges.py): `src/cumap/schemas/edges.py`
- [LLM client](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/llm/client.py): `src/cumap/llm/client.py`
- [Prompt templates](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/llm/prompts.py): `src/cumap/llm/prompts.py`
- [Configuration](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/config.py): `src/cumap/config.py`

### Review and evaluation

- [Gold annotation tools](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/gold/suggest_expert.py): `src/cumap/gold/suggest_expert.py`
- [Gold validation](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/gold/validate.py): `src/cumap/gold/validate.py`
- [Evaluation](https://github.com/zhengtat/final-year-project/tree/master/src/cumap/eval): `src/cumap/eval`
- [Reports and visualization](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/report/build.py): `src/cumap/report/build.py`
- [Gold review app](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/app/gold_editor.py): `src/cumap/app/gold_editor.py`

### Other components

- **Engineer / educator**
- [CLI workflows](https://github.com/zhengtat/final-year-project/blob/master/src/cumap/cli.py): `src/cumap/cli.py`

## Connections

- Engineer / educator → CLI workflows: runs commands (evidence: `README.md`)
- CLI workflows → Dataset preparation: prepares datasets (evidence: `src/cumap/cli.py`)
- CLI workflows → Textbook fetch: fetches source (evidence: `src/cumap/cli.py`)
- CLI workflows → Textbook parsing: parses sections (evidence: `src/cumap/cli.py`)
- CLI workflows → Textbook coverage: checks coverage (evidence: `src/cumap/cli.py`)
- Textbook fetch → Textbook parsing: provides source
- CLI workflows → Expert KG pipeline: builds expert graph
- Expert KG pipeline → Concept canonicalization: canonicalizes mentions (evidence: `src/cumap/expert_kg/pipeline.py`)
- Expert KG pipeline → Relation extraction: resolves relations (evidence: `src/cumap/expert_kg/pipeline.py`)
- Expert KG pipeline → KG snapshots: creates snapshots (evidence: `src/cumap/expert_kg/pipeline.py`)
- CLI workflows → Student graph extraction: extracts answer graph (evidence: `src/cumap/cli.py`)
- Student graph extraction → Graph diagnosis: supplies student graph
- Expert KG pipeline → Graph diagnosis: supplies expert graph
- Graph diagnosis → Relation registry: aligns relations
- CLI workflows → Gold annotation tools: suggests annotations (evidence: `src/cumap/cli.py`)
- Gold annotation tools → LLM client: requests suggestions (evidence: `src/cumap/gold/suggest_expert.py`)
- Gold annotation tools → Gold validation: verifies quotes (evidence: `src/cumap/gold/suggest_expert.py`)
- CLI workflows → Gold validation: validates gold (evidence: `src/cumap/cli.py`)
- CLI workflows → Evaluation: runs evaluation (evidence: `src/cumap/cli.py`)
- CLI workflows → Reports and visualization: builds demo reports (evidence: `src/cumap/cli.py`)
- Reports and visualization → KG snapshots: loads snapshots (evidence: `src/cumap/report/build.py`)
- Engineer / educator → Gold review app: reviews annotations
- Gold review app → Gold validation: validates edits (evidence: `src/cumap/app/gold_editor.py`)
- Gold annotation tools → Graph schemas: constructs graph records (evidence: `src/cumap/gold/suggest_expert.py`)
- LLM client → Configuration: reads settings (evidence: `src/cumap/llm/client.py`)
- Gold annotation tools → Prompt templates: renders prompts (evidence: `src/cumap/gold/suggest_expert.py`)
- LLM client → Prompt templates: uses templates
