# akporh/agentic-payroll-platform architecture

> Architecture diagram of the GitHub repository akporh/agentic-payroll-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akporh/agentic-payroll-platform
- Repository: https://github.com/akporh/agentic-payroll-platform
- Video tour (about a minute): https://gitdiagram.com/akporh/agentic-payroll-platform/video

## Overview

This is a Nigerian payroll bureau platform: operators configure a workspace and employee compensation, prepare period inputs, run deterministic payroll, review results, and produce compliance outputs. The backend separates HTTP routes, application orchestration, payroll/onboarding domain logic, and persistence. Timesheet derivation is a distinct input-preparation stage. The README emphasizes statutory rules, auditability, and manual reporting; the tree supports these capabilities. Several route-to-service details are unsampled, so those internal links are left out rather than inferred.

Main entry points: [`backend/api/main.py`](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/main.py) (FastAPI app), [`backend/infra/repositories`](https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/infra/repositories) (Payroll repositories), [`backend/application/payroll_run_service.py`](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_run_service.py) (Payroll run orchestration), [`backend/api/routes/payroll.py`](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/payroll.py) (Payroll routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Bureau interface"]
  node_router["Workspace screens<br/>[router.tsx]"]
  node_pages["Payroll screens"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["HTTP API"]
  node_apiapp["FastAPI app<br/>[main.py]"]
  node_onboarding_routes["Onboarding routes<br/>[onboarding.py]"]
  node_payroll_routes["Payroll routes<br/>[payroll.py]"]
  node_input_routes["Payroll input routes<br/>[payroll_input.py]"]
  node_workspace_routes["Workspace routes<br/>[workspace.py]"]
end

subgraph group_setup["Workspace setup"]
  node_onboarding["Onboarding workflow"]
  node_onboard_review["Configuration review<br/>[review_runner.py]"]
  node_state_inference["Workspace readiness<br/>[state_inference.py]"]
end

subgraph group_payroll["Payroll processing"]
  node_timesheet["Timesheet derivation"]
  node_readiness["Run readiness"]
  node_run_service["Payroll run orchestration"]
  node_calculator["Payroll calculation<br/>[calculator.py]"]
  node_statutory["Statutory rules"]
  node_approval["Run approval"]
  node_exports["Compliance exports"]
end

subgraph group_data["Persistence and audit"]
  node_repositories["Payroll repositories"]
  node_workspace_repo["Workspace repository<br/>[workspace_repo.py]"]
  node_database[("PostgreSQL")]
  node_audit["Audit and event history<br/>[audit_log_repo.py]"]
end

node_operator(("Bureau operator"))

node_operator -->|"uses screens"| node_router
node_router -->|"routes to"| node_pages
node_pages -->|"requests data"| node_client
node_client -->|"calls API"| node_apiapp
node_apiapp -->|"registers"| node_onboarding_routes
node_apiapp -->|"registers"| node_payroll_routes
node_apiapp -->|"registers"| node_input_routes
node_apiapp -->|"registers"| node_workspace_routes
node_onboarding_routes -->|"handles onboarding"| node_onboarding
node_onboarding -->|"reviews configuration"| node_onboard_review
node_onboard_review -->|"infers state"| node_state_inference
node_state_inference -->|"loads workspace"| node_workspace_repo
node_workspace_repo -->|"reads and writes"| node_database
node_input_routes -->|"handles derivation"| node_timesheet
node_timesheet -->|"stores derived inputs"| node_repositories
node_payroll_routes -->|"checks run readiness"| node_readiness
node_payroll_routes -->|"orchestrates run"| node_run_service
node_run_service -->|"calculates payroll"| node_calculator
node_calculator -->|"evaluates deductions"| node_statutory
node_run_service -->|"persists run results"| node_repositories
node_approval -->|"updates run state"| node_repositories
node_exports -->|"reads payroll data"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_run_service -.->|"records execution"| node_audit

click node_router "https://github.com/akporh/agentic-payroll-platform/blob/uat/frontend/src/router.tsx"
click node_pages "https://github.com/akporh/agentic-payroll-platform/tree/uat/frontend/src/pages"
click node_client "https://github.com/akporh/agentic-payroll-platform/blob/uat/frontend/src/api/client.ts"
click node_apiapp "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/main.py"
click node_onboarding_routes "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/onboarding.py"
click node_payroll_routes "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/payroll.py"
click node_input_routes "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/payroll_input.py"
click node_workspace_routes "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/workspace.py"
click node_onboarding "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/onboarding_service.py"
click node_onboard_review "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/domain/onboarding/review_runner.py"
click node_state_inference "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/domain/onboarding/state_inference.py"
click node_timesheet "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/timesheet_derivation_service.py"
click node_readiness "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_readiness_service.py"
click node_run_service "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_run_service.py"
click node_calculator "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/domain/payroll/calculator.py"
click node_statutory "https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/domain/rules"
click node_approval "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_approval_service.py"
click node_exports "https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/application/exports"
click node_repositories "https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/infra/repositories"
click node_workspace_repo "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/infra/db/repositories/workspace_repo.py"
click node_database "https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/infra/db/models"
click node_audit "https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/infra/repositories/audit_log_repo.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_router,node_pages,node_client toneBlue
class node_apiapp,node_onboarding_routes,node_payroll_routes,node_input_routes,node_workspace_routes toneAmber
class node_onboarding,node_onboard_review,node_state_inference toneMint
class node_timesheet,node_readiness,node_run_service,node_calculator,node_statutory,node_approval,node_exports toneRose
class node_repositories,node_workspace_repo,node_database,node_audit,node_operator toneIndigo
```

## Components

### Bureau interface

- [Workspace screens](https://github.com/akporh/agentic-payroll-platform/blob/uat/frontend/src/router.tsx): `frontend/src/router.tsx`
- [Payroll screens](https://github.com/akporh/agentic-payroll-platform/tree/uat/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/akporh/agentic-payroll-platform/blob/uat/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### HTTP API

- [FastAPI app](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/main.py): `backend/api/main.py`
- [Onboarding routes](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/onboarding.py): `backend/api/routes/onboarding.py`
- [Payroll routes](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/payroll.py): `backend/api/routes/payroll.py`
- [Payroll input routes](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/payroll_input.py): `backend/api/routes/payroll_input.py`
- [Workspace routes](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/api/routes/workspace.py): `backend/api/routes/workspace.py`

### Workspace setup

- [Onboarding workflow](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/onboarding_service.py): `backend/application/onboarding_service.py`
- [Configuration review](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/domain/onboarding/review_runner.py): `backend/domain/onboarding/review_runner.py`
- [Workspace readiness](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/domain/onboarding/state_inference.py): `backend/domain/onboarding/state_inference.py`

### Payroll processing

- [Timesheet derivation](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/timesheet_derivation_service.py): `backend/application/timesheet_derivation_service.py`
- [Run readiness](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_readiness_service.py): `backend/application/payroll_readiness_service.py`
- [Payroll run orchestration](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_run_service.py): `backend/application/payroll_run_service.py`
- [Payroll calculation](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/domain/payroll/calculator.py): `backend/domain/payroll/calculator.py`
- [Statutory rules](https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/domain/rules): `backend/domain/rules`
- [Run approval](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/application/payroll_approval_service.py): `backend/application/payroll_approval_service.py`
- [Compliance exports](https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/application/exports): `backend/application/exports`

### Persistence and audit

- [Payroll repositories](https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/infra/repositories): `backend/infra/repositories`
- [Workspace repository](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/infra/db/repositories/workspace_repo.py): `backend/infra/db/repositories/workspace_repo.py`
- [PostgreSQL](https://github.com/akporh/agentic-payroll-platform/tree/uat/backend/infra/db/models): `backend/infra/db/models`
- [Audit and event history](https://github.com/akporh/agentic-payroll-platform/blob/uat/backend/infra/repositories/audit_log_repo.py): `backend/infra/repositories/audit_log_repo.py`

### Other components

- **Bureau operator**

## Connections

- Bureau operator → Workspace screens: uses screens
- Workspace screens → Payroll screens: routes to
- Payroll screens → API client: requests data
- API client → FastAPI app: calls API
- FastAPI app → Onboarding routes: registers
- FastAPI app → Payroll routes: registers
- FastAPI app → Payroll input routes: registers
- FastAPI app → Workspace routes: registers
- Onboarding routes → Onboarding workflow: handles onboarding
- Onboarding workflow → Configuration review: reviews configuration
- Configuration review → Workspace readiness: infers state
- Workspace readiness → Workspace repository: loads workspace
- Workspace repository → PostgreSQL: reads and writes
- Payroll input routes → Timesheet derivation: handles derivation
- Timesheet derivation → Payroll repositories: stores derived inputs
- Payroll routes → Run readiness: checks run readiness
- Payroll routes → Payroll run orchestration: orchestrates run
- Payroll run orchestration → Payroll calculation: calculates payroll
- Payroll calculation → Statutory rules: evaluates deductions
- Payroll run orchestration → Payroll repositories: persists run results
- Run approval → Payroll repositories: updates run state
- Compliance exports → Payroll repositories: reads payroll data
- Payroll repositories → PostgreSQL: reads and writes
- Payroll run orchestration → Audit and event history: records execution