# subhrajit-mandal/top-sheet-automation architecture

> Architecture diagram of the GitHub repository subhrajit-mandal/top-sheet-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/subhrajit-mandal/top-sheet-automation
- Repository: https://github.com/subhrajit-mandal/top-sheet-automation

## Overview

This is a single-script application for preparing class top sheets from an Excel marks workbook. Its principal workflow reads student records, then either generates sheets from a template or completes student-submitted sheets, distributing marks by the template’s question sections and producing documents, PDFs, and a report. The README documents the major capabilities; the source excerpt is partial, so internal call ownership cannot be verified and the graph groups responsibilities implemented in the same script rather than implying separate modules.

Main entry points: [`generate_top_sheets.py`](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py) (Generate sheets), [`config.json`](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/config.json) (Exam configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and rules"]
  node_workbook["Marks workbook"]
  node_template["Word template"]
  node_submissions["Submitted sheets"]
  node_configuration["Exam configuration<br/>[config.json]"]
  node_settings["Run settings"]
end

subgraph group_processing["Sheet processing"]
  node_student_records["Student records"]
  node_preflight["Input validation"]
  node_mode_selection["Run mode"]
  node_section_rules["Question sections"]
  node_mark_distribution["Question marks"]
  node_sheet_generation["Generate sheets"]
  node_submission_completion["Complete submissions"]
  node_signature["Typed signature"]
  node_seal["Official seal"]
end

subgraph group_outputs["Outputs and integrations"]
  node_documents["Completed DOCX"]
  node_pdf_export["PDF export"]
  node_pdf_engine["Word or LibreOffice"]
  node_run_report["Run report CSV"]
end

node_operator(("Operator"))

node_operator -->|"selects"| node_workbook
node_operator -->|"selects"| node_template
node_operator -->|"selects"| node_submissions
node_operator -->|"sets values"| node_settings
node_workbook -->|"reads records"| node_student_records
node_student_records -->|"validates"| node_preflight
node_configuration -->|"defines rules"| node_preflight
node_operator -->|"chooses mode"| node_mode_selection
node_template -->|"provides rows"| node_section_rules
node_section_rules -->|"sets constraints"| node_mark_distribution
node_student_records -->|"supplies totals"| node_mark_distribution
node_student_records -->|"supplies details"| node_sheet_generation
node_template -->|"provides layout"| node_sheet_generation
node_mark_distribution -->|"provides marks"| node_sheet_generation
node_student_records -->|"matches rolls"| node_submission_completion
node_submissions -->|"provides sheets"| node_submission_completion
node_mark_distribution -->|"provides marks"| node_submission_completion
node_sheet_generation -->|"adds signature"| node_signature
node_sheet_generation -->|"produces"| node_documents
node_submission_completion -->|"saves"| node_documents
node_operator -.->|"selects optionally"| node_seal
node_seal -.->|"stamps optionally"| node_documents
node_documents -->|"exports"| node_pdf_export
node_pdf_export -->|"uses"| node_pdf_engine
node_submission_completion -->|"records statuses"| node_run_report
node_sheet_generation -->|"records results"| node_run_report

click node_configuration "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/config.json"
click node_settings "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_student_records "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_preflight "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_mode_selection "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_section_rules "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_mark_distribution "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_sheet_generation "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_submission_completion "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_signature "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_seal "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_documents "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_pdf_export "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py"
click node_run_report "https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.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_workbook,node_template,node_submissions,node_configuration,node_settings toneBlue
class node_student_records,node_preflight,node_mode_selection,node_section_rules,node_mark_distribution,node_sheet_generation,node_submission_completion,node_signature,node_seal toneAmber
class node_documents,node_pdf_export,node_pdf_engine,node_run_report toneMint
class node_operator toneIndigo
```

## Components

### Inputs and rules

- **Marks workbook**
- **Word template**
- **Submitted sheets**
- [Exam configuration](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/config.json): `config.json`
- [Run settings](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`

### Sheet processing

- [Student records](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Input validation](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Run mode](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Question sections](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Question marks](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Generate sheets](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Complete submissions](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Typed signature](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [Official seal](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`

### Outputs and integrations

- [Completed DOCX](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- [PDF export](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`
- **Word or LibreOffice**
- [Run report CSV](https://github.com/subhrajit-mandal/top-sheet-automation/blob/master/generate_top_sheets.py): `generate_top_sheets.py`

### Other components

- **Operator**

## Connections

- Operator → Marks workbook: selects (evidence: `README.md`)
- Operator → Word template: selects (evidence: `README.md`)
- Operator → Submitted sheets: selects (evidence: `README.md`)
- Operator → Run settings: sets values (evidence: `README.md`)
- Marks workbook → Student records: reads records (evidence: `README.md`)
- Student records → Input validation: validates (evidence: `README.md`)
- Exam configuration → Input validation: defines rules (evidence: `README.md`)
- Operator → Run mode: chooses mode (evidence: `README.md`)
- Word template → Question sections: provides rows (evidence: `README.md`)
- Question sections → Question marks: sets constraints (evidence: `README.md`)
- Student records → Question marks: supplies totals (evidence: `README.md`)
- Student records → Generate sheets: supplies details (evidence: `README.md`)
- Word template → Generate sheets: provides layout (evidence: `README.md`)
- Question marks → Generate sheets: provides marks (evidence: `README.md`)
- Student records → Complete submissions: matches rolls (evidence: `README.md`)
- Submitted sheets → Complete submissions: provides sheets (evidence: `README.md`)
- Question marks → Complete submissions: provides marks (evidence: `README.md`)
- Generate sheets → Typed signature: adds signature (evidence: `README.md`)
- Generate sheets → Completed DOCX: produces (evidence: `README.md`)
- Complete submissions → Completed DOCX: saves (evidence: `README.md`)
- Operator → Official seal: selects optionally (evidence: `README.md`)
- Official seal → Completed DOCX: stamps optionally (evidence: `README.md`)
- Completed DOCX → PDF export: exports (evidence: `README.md`)
- PDF export → Word or LibreOffice: uses (evidence: `README.md`)
- Complete submissions → Run report CSV: records statuses (evidence: `README.md`)
- Generate sheets → Run report CSV: records results (evidence: `README.md`)