How akporh/agentic-payroll-platform works
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: main.py FastAPI app · repositories Payroll repositories · payroll_run_service.py Payroll run orchestration · payroll.py Payroll routes
Components 23
Bureau interface
- Workspace screens
frontend/src/router.tsx - Payroll screens
frontend/src/pages - API client
frontend/src/api/client.ts
HTTP API
- FastAPI app
backend/api/main.py - Onboarding routes
backend/api/routes/onboarding.py - Payroll routes
backend/api/routes/payroll.py - Payroll input routes
backend/api/routes/payroll_input.py - Workspace routes
backend/api/routes/workspace.py
Workspace setup
- Onboarding workflow
backend/application/onboarding_service.py - Configuration review
backend/domain/onboarding/review_runner.py - Workspace readiness
backend/domain/onboarding/state_inference.py
Payroll processing
- Timesheet derivation
backend/application/timesheet_derivation_service.py - Run readiness
backend/application/payroll_readiness_service.py - Payroll run orchestration
backend/application/payroll_run_service.py - Payroll calculation
backend/domain/payroll/calculator.py - Statutory rules
backend/domain/rules - Run approval
backend/application/payroll_approval_service.py - Compliance exports
backend/application/exports
Persistence and audit
- Payroll repositories
backend/infra/repositories - Workspace repository
backend/infra/db/repositories/workspace_repo.py - PostgreSQL
backend/infra/db/models - Audit and event history
backend/infra/repositories/audit_log_repo.py
Other components
- Bureau operator
Connections 24
- 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