# hanii-tech/automated-payslip-generation-system architecture

> Architecture diagram of the GitHub repository hanii-tech/automated-payslip-generation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanii-tech/automated-payslip-generation-system
- Repository: https://github.com/hanii-tech/automated-payslip-generation-system

## Overview

This is a batch payslip-generation application: an operator starts a run, employee records are loaded and validated, payroll amounts are calculated, PDFs are created, emails are optionally sent, and outcomes are written to a manifest. The graph follows the documented workflow and sampled calls; the README also describes Excel input, although only a CSV sample appears in the tree.

Main entry points: [`src/main.py`](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/main.py) (Pipeline orchestration), [`src/utils.py`](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/utils.py) (Data loading & validation), [`src/email_sender.py`](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/email_sender.py) (Email delivery), [`run.py`](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/run.py) (Command entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run orchestration"]
  node_launcher["Command entry<br/>[run.py]"]
  node_pipeline["Pipeline orchestration<br/>[main.py]"]
end

subgraph group_payroll["Payroll processing"]
  node_employee_file["Employee CSV<br/>[employees.csv]"]
  node_data_helpers["Data loading &amp; validation<br/>[utils.py]"]
  node_pay_calculation["Net pay calculation<br/>[utils.py]"]
end

subgraph group_delivery["Payslip delivery"]
  node_pdf_builder["Payslip PDF generation<br/>[pdf_generator.py]"]
  node_email_sender["Email delivery<br/>[email_sender.py]"]
end

subgraph group_outputs["Run artifacts"]
  node_processed_file["Processed payroll CSV"]
  node_payslip_files["Payslip PDFs"]
  node_manifest["Run manifest CSV"]
end

node_operator(("Payroll operator"))
node_smtp{{"SMTP provider"}}
node_employee(("Employee recipient"))

node_operator -->|"starts run"| node_launcher
node_launcher -->|"calls"| node_pipeline
node_pipeline -->|"loads and validates"| node_data_helpers
node_data_helpers -->|"reads"| node_employee_file
node_pipeline -->|"calculates pay"| node_pay_calculation
node_pipeline -->|"saves processed data"| node_data_helpers
node_data_helpers -->|"writes"| node_processed_file
node_pipeline -->|"generates payslips"| node_pdf_builder
node_pdf_builder -->|"writes PDFs"| node_payslip_files
node_pipeline -.->|"requests delivery"| node_email_sender
node_email_sender -.->|"sends attachment"| node_smtp
node_smtp -.->|"delivers email"| node_employee
node_email_sender -.->|"reads attachment"| node_payslip_files
node_pipeline -->|"writes outcomes"| node_manifest

click node_launcher "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/run.py"
click node_pipeline "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/main.py"
click node_employee_file "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/data/employees.csv"
click node_data_helpers "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/utils.py"
click node_pay_calculation "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/utils.py"
click node_pdf_builder "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/pdf_generator.py"
click node_email_sender "https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/email_sender.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_launcher,node_pipeline toneBlue
class node_employee_file,node_data_helpers,node_pay_calculation toneAmber
class node_pdf_builder,node_email_sender toneMint
class node_processed_file,node_payslip_files,node_manifest toneRose
class node_operator,node_smtp,node_employee toneIndigo
```

## Components

### Run orchestration

- [Command entry](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/run.py): `run.py`
- [Pipeline orchestration](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/main.py): `src/main.py`

### Payroll processing

- [Employee CSV](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/data/employees.csv): `data/employees.csv`
- [Data loading & validation](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/utils.py): `src/utils.py`
- [Net pay calculation](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/utils.py): `src/utils.py`

### Payslip delivery

- [Payslip PDF generation](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/pdf_generator.py): `src/pdf_generator.py`
- [Email delivery](https://github.com/hanii-tech/automated-payslip-generation-system/blob/main/src/email_sender.py): `src/email_sender.py`

### Run artifacts

- **Processed payroll CSV**
- **Payslip PDFs**
- **Run manifest CSV**

### Other components

- **Payroll operator**
- **SMTP provider**
- **Employee recipient**

## Connections

- Payroll operator → Command entry: starts run
- Command entry → Pipeline orchestration: calls
- Pipeline orchestration → Data loading & validation: loads and validates
- Data loading & validation → Employee CSV: reads
- Pipeline orchestration → Net pay calculation: calculates pay
- Pipeline orchestration → Data loading & validation: saves processed data
- Data loading & validation → Processed payroll CSV: writes
- Pipeline orchestration → Payslip PDF generation: generates payslips
- Payslip PDF generation → Payslip PDFs: writes PDFs
- Pipeline orchestration → Email delivery: requests delivery
- Email delivery → SMTP provider: sends attachment
- SMTP provider → Employee recipient: delivers email
- Email delivery → Payslip PDFs: reads attachment
- Pipeline orchestration → Run manifest CSV: writes outcomes