# umjs/ponto-smart architecture

> Architecture diagram of the GitHub repository umjs/ponto-smart, 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/umjs/ponto-smart
- Repository: https://github.com/umjs/ponto-smart

## Overview

Ponto Smart is a Streamlit time-and-attendance application for employees and administrators. Employees use the kiosk to authenticate, record or correct PIN details, and receive a confirmation; administrators manage employees, inspect and correct time entries, and produce reports. The main runtime is concentrated in app.py, with PDF generation, hour calculations, and email delivery in utils.py, backed by Supabase. The README documents PIN lockout and audit behavior, but the excerpts do not expose their wiring in detail.

Main entry points: [`app.py`](https://github.com/umjs/ponto-smart/blob/main/app.py) (Employee kiosk), [`utils.py`](https://github.com/umjs/ponto-smart/blob/main/utils.py) (PDF generation), [`database_schema.sql`](https://github.com/umjs/ponto-smart/blob/main/database_schema.sql) (Database schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["User workflows"]
  node_runtime["App routing<br/>[app.py]"]
  node_kiosk["Employee kiosk<br/>[app.py]"]
  node_pin_access["PIN access<br/>[app.py]"]
  node_attendance["Attendance actions<br/>[app.py]"]
  node_admin_panel["Admin panel<br/>[app.py]"]
  node_employee_management["Employee management<br/>[app.py]"]
  node_entry_review["Entry review<br/>[app.py]"]
  node_corrections_audit["Corrections and audit<br/>[app.py]"]
  node_settings["Admin settings<br/>[app.py]"]
end

subgraph group_data["Persistence"]
  node_employee_data["Employee data access<br/>[app.py]"]
  node_entry_data["Time-entry data access<br/>[app.py]"]
  node_supabase[("Supabase")]
  node_schema["Database schema"]
end

subgraph group_outputs["Reports and delivery"]
  node_reporting["Report workflow<br/>[app.py]"]
  node_pdf["PDF generation<br/>[utils.py]"]
  node_hour_calculation["Hour calculation<br/>[utils.py]"]
  node_email["Email delivery<br/>[utils.py]"]
  node_employee_result["Attendance confirmation<br/>[app.py]"]
end

node_employee(("Employee"))
node_administrator(("Administrator"))
node_smtp["SMTP service"]

node_employee -->|"selects mode"| node_runtime
node_administrator -->|"selects mode"| node_runtime
node_runtime -->|"dispatches"| node_kiosk
node_runtime -->|"dispatches"| node_admin_panel
node_kiosk -->|"requests authentication"| node_pin_access
node_employee -->|"provides PIN"| node_pin_access
node_kiosk -->|"records action"| node_attendance
node_attendance -->|"loads employees"| node_employee_data
node_attendance -->|"reads and writes entries"| node_entry_data
node_attendance -->|"shows confirmation"| node_employee_result
node_admin_panel -->|"dispatches"| node_employee_management
node_admin_panel -->|"dispatches"| node_entry_review
node_admin_panel -->|"dispatches"| node_reporting
node_admin_panel -->|"dispatches"| node_settings
node_employee_management -->|"manages employees"| node_employee_data
node_entry_review -->|"loads entries"| node_entry_data
node_entry_review -->|"requests correction"| node_corrections_audit
node_corrections_audit -->|"updates entry"| node_entry_data
node_reporting -->|"loads employees"| node_employee_data
node_reporting -->|"loads entries"| node_entry_data
node_reporting -->|"generates report"| node_pdf
node_pdf -->|"calculates hours"| node_hour_calculation
node_reporting -.->|"sends report"| node_email
node_kiosk -->|"creates receipt"| node_pdf
node_kiosk -.->|"sends receipt"| node_email
node_email -.->|"delivers message"| node_smtp
node_employee_data -->|"reads and writes"| node_supabase
node_entry_data -->|"reads and writes"| node_supabase
node_schema -->|"defines tables"| node_supabase

click node_runtime "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_kiosk "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_pin_access "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_attendance "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_admin_panel "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_employee_management "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_entry_review "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_corrections_audit "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_settings "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_employee_data "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_entry_data "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_schema "https://github.com/umjs/ponto-smart/blob/main/database_schema.sql"
click node_reporting "https://github.com/umjs/ponto-smart/blob/main/app.py"
click node_pdf "https://github.com/umjs/ponto-smart/blob/main/utils.py"
click node_hour_calculation "https://github.com/umjs/ponto-smart/blob/main/utils.py"
click node_email "https://github.com/umjs/ponto-smart/blob/main/utils.py"
click node_employee_result "https://github.com/umjs/ponto-smart/blob/main/app.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_runtime,node_kiosk,node_pin_access,node_attendance,node_admin_panel,node_employee_management,node_entry_review,node_corrections_audit,node_settings toneBlue
class node_employee_data,node_entry_data,node_supabase,node_schema toneAmber
class node_reporting,node_pdf,node_hour_calculation,node_email,node_employee_result toneMint
class node_employee,node_administrator,node_smtp toneIndigo
```

## Components

### User workflows

- [App routing](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Employee kiosk](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [PIN access](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Attendance actions](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Admin panel](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Employee management](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Entry review](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Corrections and audit](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Admin settings](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`

### Persistence

- [Employee data access](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [Time-entry data access](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- **Supabase**
- [Database schema](https://github.com/umjs/ponto-smart/blob/main/database_schema.sql): `database_schema.sql`

### Reports and delivery

- [Report workflow](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`
- [PDF generation](https://github.com/umjs/ponto-smart/blob/main/utils.py): `utils.py`
- [Hour calculation](https://github.com/umjs/ponto-smart/blob/main/utils.py): `utils.py`
- [Email delivery](https://github.com/umjs/ponto-smart/blob/main/utils.py): `utils.py`
- [Attendance confirmation](https://github.com/umjs/ponto-smart/blob/main/app.py): `app.py`

### Other components

- **Employee**
- **Administrator**
- **SMTP service**

## Connections

- Employee → App routing: selects mode
- Administrator → App routing: selects mode
- App routing → Employee kiosk: dispatches
- App routing → Admin panel: dispatches
- Employee kiosk → PIN access: requests authentication
- Employee → PIN access: provides PIN
- Employee kiosk → Attendance actions: records action
- Attendance actions → Employee data access: loads employees
- Attendance actions → Time-entry data access: reads and writes entries
- Attendance actions → Attendance confirmation: shows confirmation
- Admin panel → Employee management: dispatches
- Admin panel → Entry review: dispatches
- Admin panel → Report workflow: dispatches
- Admin panel → Admin settings: dispatches
- Employee management → Employee data access: manages employees
- Entry review → Time-entry data access: loads entries
- Entry review → Corrections and audit: requests correction
- Corrections and audit → Time-entry data access: updates entry
- Report workflow → Employee data access: loads employees
- Report workflow → Time-entry data access: loads entries
- Report workflow → PDF generation: generates report
- PDF generation → Hour calculation: calculates hours
- Report workflow → Email delivery: sends report
- Employee kiosk → PDF generation: creates receipt
- Employee kiosk → Email delivery: sends receipt
- Email delivery → SMTP service: delivers message
- Employee data access → Supabase: reads and writes
- Time-entry data access → Supabase: reads and writes
- Database schema → Supabase: defines tables