# royalsuthan06/payroll_matchbox architecture

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

- Interactive diagram: https://gitdiagram.com/royalsuthan06/payroll_matchbox
- Repository: https://github.com/royalsuthan06/payroll_matchbox

## Overview

From the README + file tree, this is a **server-rendered Flask web application** (monolith) with:
- **HTML UI** via **Jinja templates** (`Payroll/templates/**`) + static CSS (`Payroll/static/**`)
- **Flask route modules / Blueprints** (e.g., `routes.py`, `employee_routes.py`, `auth_routes.py`)
- A **service layer** encapsulating business logic (`services.py`, plus specialized services like `email_service.py`, `export_service.py`)
- **Config/env** (`config.py`, `.env.example`)
- Features span **production/inventory/analytics** (README) and also **auth/users/employees/payroll** (file tree strongly suggests HR/payroll features exist or are partially implemented)

So architecturally: **Flask monolith + service layer + ORM models + SQLite + server-side rendered UI + optional JSON REST endpoints + optional integrations (email/export).**

##### Flask Web App (WSGI)
- `app.py` as entry point / app factory
- Blueprint route modules (auth/employee/core)
- Jinja templates
- Static assets
##### (Optional) SMTP server (if email enabled)

Key interactions:
- Browser ⇄ Flask App (HTTP, server-rendered HTML)
- Flask App → SMTP (email notifications)

Important note to capture:
- This is a **modular monolith** (not microservices): multiple modules/blueprints, one deployable unit, one DB.

**Goal:** make it “code-shaped”. This is where you “separate into as many components as possible”.

Inside the **Flask App** boundary, break down into:

##### Entry + Configuration
- `app.py` — app creation, registration of routes/blueprints, initialization (DB, config)
- `config.py` — config classes, env var mapping

- `app.py` → `config.py`
- `app.py` → registers route modules

##### Route/Controller Layer (HTTP endpoints)
Create components aligned to files:
- `routes.py` — core routes: dashboard, inventory, production, reports, REST `/api/*` (README mentions these)
- `employee_routes.py` — employee/payroll/attendance/salary flows (supported by templates under `templates/employee/**`)
- `auth_routes.py` — login/register/profile/preferences/users admin pages (templates under `templates/auth/**`)

- Routes → call Services
- Routes → render Templates (HTML)
- Routes → return JSON (for `/api/*`)

##### Service Layer (business logic / transactions)
Components:
- `services.py` — core domain logic (inventory changes, production logging, undo production, reporting calculations, stockout prediction, pagination)
- `email_service.py` — email sending abstraction
- `export_service.py` — export/download generation (CSV/PDF “coming soon” but file exists, so include it)

- `services.py` → Models (DB)
- `services.py` → `email_service.py` (low stock alerts / notifications)
- `services.py` → `export_service.py` (report exports)

- “DB Transactions / atomic operations + rollback”
- “Soft delete (ProductionLog.is_deleted)”
- “Audit trail via MaterialTransaction”

##### Data Access / Models
- `models.py` — RawMaterial, ProductionLog, MaterialTransaction, Recipe (README schema)
- `auth_models.py` — user/auth related tables (inferred from filename/templates)

- Models → SQLite DB

##### Flow 1: “Log Production”
Browser → `routes.py` (POST /production)
`routes.py` → `services.py` (log_production)
`services.py` → `models.py` (create ProductionLog; deduct RawMaterial; create MaterialTransaction records)
`services.py` → DB transaction commit/rollback
Return HTML redirect/updated page.

##### Flow 2: “Undo Production”
Browser → route handler
Route → `services.py` (undo_production)
Service → create reversal MaterialTransaction rows + restore inventory + soft-delete ProductionLog (`is_deleted=1`)
Commit.

##### Flow 3: “Inventory Restock”
Browser → route handler
Route → `services.py` (restock_material)
Service → update RawMaterial.quantity + write MaterialTransaction('restock').

##### Flow 4: “REST API calls”
API Client → `routes.py` (`GET /api/materials`, `/api/production/...`)
Route → `services.py` → `models.py` → DB → JSON response.

- Either present it as a **single system with multiple modules**: Production/Inventory + HR/Payroll/Auth
- Or label HR/payroll as “additional module present in codebase” if the README is outdated
- **SQLite DB located in `instance/`** as the persistence mechanism.
- Explicitly call out the **service layer** as the core design choice (README emphasizes modular architecture + business logic abstraction).

##### What “done” looks like (deliverables)
To be maximally useful for engineering discussions, produce:

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% LEVEL 1 — SYSTEM CONTEXT
%% =========================
subgraph L1["Level 1: System Context"]
  direction TB

  U["User (Browser)"]:::actor
  APIC["External API Consumer"]:::actor

  SYS["Matchbox Production Management System<br/>(Flask Monolith)"]:::system

  SMTP["Email/SMTP Provider"]:::external
  EXPORTC["Export Consumers<br/>(CSV/PDF downloads)"]:::external

  U <--> |"HTTP(S) HTML"| SYS
  APIC --> |"HTTP(S) JSON (/api/*)"| SYS
  SYS -.-> |"SMTP/API"| SMTP
  SYS -.-> |"Generated files"| EXPORTC
end

%% =========================
%% LEVEL 2 — CONTAINERS
%% =========================
subgraph L2["Level 2: Container Diagram (Runtime)"]
  direction TB

  BROWSER["Web Browser"]:::container
  WSGI["Flask Web App (WSGI)<br/>Server-rendered UI + JSON API"]:::container
  DB[("SQLite Database<br/>(instance/payroll_fixed.db)")]:::db
  SMTP2["SMTP Server (optional)"]:::external

  BROWSER <--> |"HTTP HTML/CSS"| WSGI
  WSGI <--> |"ORM/SQL"| DB
  WSGI -.-> |"Email notifications"| SMTP2

  NOTE2["Notes:<br/>• Modular monolith (blueprints/modules)<br/>• Single deployable unit + single DB"]:::note
  WSGI --- NOTE2
end

%% =========================
%% LEVEL 3 — COMPONENTS (CODE-SHAPED)
%% =========================
subgraph L3["Level 3: Component Diagram (Mapped to Repo Files)"]
  direction TB

  subgraph APP["Flask App Boundary (Payroll/)"]
    direction TB

    %% Entry + Config
    subgraph ENTRY["Entry + Configuration"]
      direction TB
      APPPY["App Entry / App Factory<br/>(app.py)"]:::entry
      CFG["Configuration / Env Mapping<br/>(config.py)"]:::config
      ENVX["Environment Example<br/>(.env.example)"]:::config
      RUNPS["Runtime Launch Script<br/>(run.ps1)"]:::ops

      APPPY --> |"loads"| CFG
      CFG --> |"reads"| ENVX
      RUNPS --> |"launches"| APPPY
    end

    %% Routes / Controllers
    subgraph ROUTES["Routes / Controllers (Blueprint modules)"]
      direction TB
      RCORE["Core Routes + /api/*<br/>(routes.py)"]:::route
      REMP["Employee/Payroll Routes<br/>(employee_routes.py)"]:::route
      RAUTH["Auth/User Routes<br/>(auth_routes.py)"]:::route
    end

    %% Services
    subgraph SERVICES["Service Layer (Business Logic)"]
      direction TB
      SVC["Core Domain Services<br/>(services.py)"]:::service
      EMAIL["Email Service<br/>(email_service.py)"]:::service
      EXPORT["Export Service<br/>(export_service.py)"]:::service

      SVC -.-> |"optional:send"| EMAIL
      SVC -.-> |"optional:generate"| EXPORT
    end

    %% Models / Persistence
    subgraph DATA["Models + Persistence"]
      direction TB
      MDL["Domain Models<br/>(models.py)<br/>• RawMaterial<br/>• Recipe<br/>• ProductionLog (soft delete)<br/>• MaterialTransaction (audit)"]:::model
      AMDL["Auth Models<br/>(auth_models.py)"]:::model
      SQL[("SQLite<br/>(instance/)")]:::db

      MDL --> |"ORM/SQL"| SQL
      AMDL --> |"ORM/SQL"| SQL
    end

    %% Presentation
    subgraph UI["Presentation (Server-rendered UI)"]
      direction TB
      TROOT["Jinja Templates Root<br/>(templates/)"]:::ui
      TAUTH["Auth Templates<br/>(templates/auth/)"]:::ui
      TEMP["Employee/Payroll Templates<br/>(templates/employee/)"]:::ui
      TERR["Error Pages<br/>(templates/errors/)"]:::ui

      TDASH["dashboard.html"]:::ui
      TINV["inventory.html"]:::ui
      TPROD["production.html"]:::ui
      TREP["reports.html"]:::ui
      TAN["analytics.html"]:::ui
      TPAY["payroll.html"]:::ui

      STATIC["Static Assets<br/>(static/)"]:::static
      CSS["Main Stylesheet<br/>(static/css/style.css)"]:::static

      TROOT --> TAUTH
      TROOT --> TEMP
      TROOT --> TERR
      TROOT --> TDASH
      TROOT --> TINV
      TROOT --> TPROD
      TROOT --> TREP
      TROOT --> TAN
      TROOT --> TPAY

      STATIC --> CSS
    end

    %% Inter-layer wiring
    APPPY --> |"registers"| RCORE
    APPPY --> |"registers"| REMP
    APPPY --> |"registers"| RAUTH

    RCORE --> |"calls"| SVC
    REMP --> |"calls"| SVC
    RAUTH --> |"calls"| SVC

    SVC --> |"reads/writes"| MDL
    SVC --> |"auth/users"| AMDL

    RCORE --> |"renders"| TROOT
    REMP --> |"renders"| TROOT
    RAUTH --> |"renders"| TROOT

    RCORE --> |"returns"| JSON["JSON Responses<br/>(/api/*)"]:::api

    %% Browser/UI linkage
    BOUNDARYNOTE["Key properties:<br/>• Atomic DB transactions + rollback<br/>• Audit trail via MaterialTransaction<br/>• Soft delete on ProductionLog.is_deleted<br/>• Pagination for list views<br/>• Server-rendered UI + JSON API"]:::note
    SERVICES --- BOUNDARYNOTE
  end
end

%% =========================
%% KEY FLOWS (ANNOTATED)
%% =========================
subgraph FLOWS["Key Flows (Annotated)"]
  direction TB

  F1["Flow 1: Log Production<br/>POST /production"]:::flow
  F2["Flow 2: Undo Production<br/>POST /production/{id}/undo"]:::flow
  F3["Flow 3: Inventory Restock<br/>POST /inventory/restock"]:::flow
  F4["Flow 4: REST API Calls<br/>GET /api/materials | /api/production/*"]:::flow

  F1 --> |"route:handle"| RCORE
  RCORE --> |"svc:log_production"| SVC
  SVC --> |"tx:create ProductionLog + deduct RawMaterial + write MaterialTransaction"| MDL
  MDL --> |"commit/rollback"| SQL

  F2 --> |"route:handle"| RCORE
  RCORE --> |"svc:undo_production"| SVC
  SVC --> |"tx:reversal MaterialTransaction + restore inventory + soft delete ProductionLog"| MDL
  MDL --> |"commit"| SQL

  F3 --> |"route:handle"| RCORE
  RCORE --> |"svc:restock_material"| SVC
  SVC --> |"update RawMaterial + write MaterialTransaction(restock)"| MDL
  MDL --> |"commit"| SQL

  F4 --> |"API client calls"| RCORE
  RCORE --> |"svc:query"| SVC
  SVC --> |"read"| MDL
  RCORE --> |"json"| JSON
end

%% =========================
%% CLICK EVENTS (from component_mapping)
%% =========================
click APPPY "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/app.py"
click CFG "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/config.py"
click RCORE "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/routes.py"
click REMP "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/employee_routes.py"
click RAUTH "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/auth_routes.py"
click SVC "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/services.py"
click EMAIL "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/email_service.py"
click EXPORT "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/export_service.py"
click MDL "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/models.py"
click AMDL "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/auth_models.py"
click TROOT "https://github.com/royalsuthan06/payroll_matchbox/tree/main/Payroll/templates/"
click TAUTH "https://github.com/royalsuthan06/payroll_matchbox/tree/main/Payroll/templates/auth/"
click TEMP "https://github.com/royalsuthan06/payroll_matchbox/tree/main/Payroll/templates/employee/"
click TERR "https://github.com/royalsuthan06/payroll_matchbox/tree/main/Payroll/templates/errors/"
click TINV "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/templates/inventory.html"
click TPROD "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/templates/production.html"
click TREP "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/templates/reports.html"
click TAN "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/templates/analytics.html"
click TDASH "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/templates/dashboard.html"
click TPAY "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/templates/payroll.html"
click STATIC "https://github.com/royalsuthan06/payroll_matchbox/tree/main/Payroll/static/"
click CSS "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/static/css/style.css"
click RUNPS "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/run.ps1"
click ENVX "https://github.com/royalsuthan06/payroll_matchbox/blob/main/Payroll/.env.example"
click DB "https://github.com/royalsuthan06/payroll_matchbox/blob/main/instance/payroll_fixed.db"

%% =========================
%% STYLES
%% =========================
classDef actor fill:#eeeeee,stroke:#666,color:#111,stroke-width:1px;
classDef system fill:#dbeafe,stroke:#1d4ed8,color:#0b1f44,stroke-width:2px;
classDef external fill:#f3f4f6,stroke:#6b7280,color:#111,stroke-width:1px,stroke-dasharray: 5 4;
classDef container fill:#e0f2fe,stroke:#0284c7,color:#0b1f44,stroke-width:1.5px;

classDef entry fill:#e0e7ff,stroke:#4338ca,color:#111,stroke-width:1.5px;
classDef config fill:#ede9fe,stroke:#6d28d9,color:#111,stroke-width:1.5px;
classDef ops fill:#f1f5f9,stroke:#334155,color:#111,stroke-width:1.5px;

classDef route fill:#bfdbfe,stroke:#2563eb,color:#111,stroke-width:1.5px;
classDef service fill:#bbf7d0,stroke:#16a34a,color:#111,stroke-width:1.5px;
classDef model fill:#fed7aa,stroke:#ea580c,color:#111,stroke-width:1.5px;
classDef db fill:#fdba74,stroke:#c2410c,color:#111,stroke-width:2px;

classDef ui fill:#f5d0fe,stroke:#a21caf,color:#111,stroke-width:1.5px;
classDef static fill:#ddd6fe,stroke:#7c3aed,color:#111,stroke-width:1.5px;
classDef api fill:#c7d2fe,stroke:#4f46e5,color:#111,stroke-width:1.5px;

classDef note fill:#fff7ed,stroke:#9a3412,color:#111,stroke-width:1px,stroke-dasharray: 3 3;
classDef flow fill:#fef9c3,stroke:#ca8a04,color:#111,stroke-width:1.5px;
```
