# hmooodyy/flussra architecture

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

- Interactive diagram: https://gitdiagram.com/hmooodyy/flussra
- Repository: https://github.com/hmooodyy/flussra

## Overview

Flussra is a payroll-management application with a React/TypeScript client and FastAPI/PostgreSQL backend. Users authenticate, manage workforce and payroll policy, create and calculate payroll periods, submit them for manager review, and inspect payroll results. The graph separates policy setup, operational payroll, review, and supporting administration. Frontend routing, selected service calls, and application router registration are evidenced by excerpts or the source index; unsampled capabilities are represented at their exact subsystem paths, with uncertain internal links omitted.

Main entry points: [`backend/app/main.py`](https://github.com/hmooodyy/flussra/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/hmooodyy/flussra/blob/main/frontend/src/App.tsx) (React application), [`frontend/src/pages/ReviewPage.tsx`](https://github.com/hmooodyy/flussra/blob/main/frontend/src/pages/ReviewPage.tsx) (Review workspace), [`frontend/src/pages/payroll`](https://github.com/hmooodyy/flussra/tree/main/frontend/src/pages/payroll) (Payroll workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["React application<br/>[App.tsx]"]
  node_payroll_ui["Payroll workspace"]
  node_setup_ui["Setup workspace"]
  node_review_ui["Review workspace<br/>[ReviewPage.tsx]"]
  node_api_client["API clients<br/>[apiClient.ts]"]
end

subgraph group_platform["API and access"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[security.py]"]
  node_authorization["Branch permissions<br/>[service.py]"]
end

subgraph group_operations["Workforce and setup"]
  node_workforce["Workforce records<br/>[service.py]"]
  node_payroll_setup["Payroll policy setup<br/>[payroll_policy.py]"]
  node_company_settings["Company settings<br/>[service.py]"]
end

subgraph group_payroll["Payroll lifecycle"]
  node_payroll_periods["Payroll periods"]
  node_payroll_calculation["Payroll calculation"]
end

subgraph group_governance["Review and administration"]
  node_review["Manager review<br/>[service.py]"]
  node_admin["Users and roles<br/>[service.py]"]
  node_dashboard["Dashboard<br/>[service.py]"]
  node_transfer["Transfer requests<br/>[service.py]"]
  node_cdpi["Pay-item workflows<br/>[service.py]"]
end

node_employee(("Payroll user"))

node_employee -->|"uses"| node_web
node_web -->|"routes to"| node_payroll_ui
node_web -->|"routes to"| node_setup_ui
node_web -->|"routes to"| node_review_ui
node_payroll_ui -->|"calls"| node_api_client
node_review_ui -->|"calls"| node_api_client
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_payroll_periods
node_api -->|"registers routes"| node_payroll_setup
node_api -->|"registers routes"| node_review
node_api -->|"registers routes"| node_company_settings
node_api -->|"registers routes"| node_admin
node_api -->|"registers routes"| node_dashboard
node_api -->|"registers routes"| node_transfer
node_api -->|"registers routes"| node_workforce
node_api -->|"registers routes"| node_cdpi
node_payroll_periods -->|"uses calculation"| node_payroll_calculation
node_review_ui -->|"loads snapshot and decides"| node_review
node_payroll_setup -.->|"provides policy"| node_payroll_ui
node_api_client -.->|"sends requests"| node_api
node_workforce -.->|"supplies workforce data"| node_payroll_calculation
node_authorization -->|"checks access"| node_workforce

click node_web "https://github.com/hmooodyy/flussra/blob/main/frontend/src/App.tsx"
click node_payroll_ui "https://github.com/hmooodyy/flussra/tree/main/frontend/src/pages/payroll"
click node_setup_ui "https://github.com/hmooodyy/flussra/tree/main/frontend/src/pages/settings/payroll"
click node_review_ui "https://github.com/hmooodyy/flussra/blob/main/frontend/src/pages/ReviewPage.tsx"
click node_api_client "https://github.com/hmooodyy/flussra/blob/main/frontend/src/lib/apiClient.ts"
click node_api "https://github.com/hmooodyy/flussra/blob/main/backend/app/main.py"
click node_auth "https://github.com/hmooodyy/flussra/blob/main/backend/app/auth/security.py"
click node_authorization "https://github.com/hmooodyy/flussra/blob/main/backend/app/core/service.py"
click node_workforce "https://github.com/hmooodyy/flussra/blob/main/backend/app/workforce/service.py"
click node_payroll_setup "https://github.com/hmooodyy/flussra/blob/main/backend/app/payroll_setup/payroll_policy.py"
click node_company_settings "https://github.com/hmooodyy/flussra/blob/main/backend/app/settings/service.py"
click node_payroll_periods "https://github.com/hmooodyy/flussra/blob/main/backend/app/payroll/period_lifecycle.py"
click node_payroll_calculation "https://github.com/hmooodyy/flussra/blob/main/backend/app/payroll/period_calculation.py"
click node_review "https://github.com/hmooodyy/flussra/blob/main/backend/app/review/service.py"
click node_admin "https://github.com/hmooodyy/flussra/blob/main/backend/app/admin/service.py"
click node_dashboard "https://github.com/hmooodyy/flussra/blob/main/backend/app/dashboard/service.py"
click node_transfer "https://github.com/hmooodyy/flussra/blob/main/backend/app/transfer/service.py"
click node_cdpi "https://github.com/hmooodyy/flussra/blob/main/backend/app/cdpi/service.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_web,node_payroll_ui,node_setup_ui,node_review_ui,node_api_client,node_employee toneBlue
class node_api,node_auth,node_authorization toneAmber
class node_workforce,node_payroll_setup,node_company_settings toneMint
class node_payroll_periods,node_payroll_calculation toneRose
class node_review,node_admin,node_dashboard,node_transfer,node_cdpi toneIndigo
```

## Components

### Web client

- [React application](https://github.com/hmooodyy/flussra/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Payroll workspace](https://github.com/hmooodyy/flussra/tree/main/frontend/src/pages/payroll): `frontend/src/pages/payroll`
- [Setup workspace](https://github.com/hmooodyy/flussra/tree/main/frontend/src/pages/settings/payroll): `frontend/src/pages/settings/payroll`
- [Review workspace](https://github.com/hmooodyy/flussra/blob/main/frontend/src/pages/ReviewPage.tsx): `frontend/src/pages/ReviewPage.tsx`
- [API clients](https://github.com/hmooodyy/flussra/blob/main/frontend/src/lib/apiClient.ts): `frontend/src/lib/apiClient.ts`

### API and access

- [FastAPI application](https://github.com/hmooodyy/flussra/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/hmooodyy/flussra/blob/main/backend/app/auth/security.py): `backend/app/auth/security.py`
- [Branch permissions](https://github.com/hmooodyy/flussra/blob/main/backend/app/core/service.py): `backend/app/core/service.py`

### Workforce and setup

- [Workforce records](https://github.com/hmooodyy/flussra/blob/main/backend/app/workforce/service.py): `backend/app/workforce/service.py`
- [Payroll policy setup](https://github.com/hmooodyy/flussra/blob/main/backend/app/payroll_setup/payroll_policy.py): `backend/app/payroll_setup/payroll_policy.py`
- [Company settings](https://github.com/hmooodyy/flussra/blob/main/backend/app/settings/service.py): `backend/app/settings/service.py`

### Payroll lifecycle

- [Payroll periods](https://github.com/hmooodyy/flussra/blob/main/backend/app/payroll/period_lifecycle.py): `backend/app/payroll/period_lifecycle.py`
- [Payroll calculation](https://github.com/hmooodyy/flussra/blob/main/backend/app/payroll/period_calculation.py): `backend/app/payroll/period_calculation.py`

### Review and administration

- [Manager review](https://github.com/hmooodyy/flussra/blob/main/backend/app/review/service.py): `backend/app/review/service.py`
- [Users and roles](https://github.com/hmooodyy/flussra/blob/main/backend/app/admin/service.py): `backend/app/admin/service.py`
- [Dashboard](https://github.com/hmooodyy/flussra/blob/main/backend/app/dashboard/service.py): `backend/app/dashboard/service.py`
- [Transfer requests](https://github.com/hmooodyy/flussra/blob/main/backend/app/transfer/service.py): `backend/app/transfer/service.py`
- [Pay-item workflows](https://github.com/hmooodyy/flussra/blob/main/backend/app/cdpi/service.py): `backend/app/cdpi/service.py`

### Other components

- **Payroll user**

## Connections

- Payroll user → React application: uses (evidence: `README.md`)
- React application → Payroll workspace: routes to (evidence: `frontend/src/App.tsx`)
- React application → Setup workspace: routes to (evidence: `frontend/src/App.tsx`)
- React application → Review workspace: routes to (evidence: `frontend/src/App.tsx`)
- Payroll workspace → API clients: calls
- Review workspace → API clients: calls (evidence: `frontend/src/pages/ReviewPage.tsx`)
- FastAPI application → Authentication: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Payroll periods: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Payroll policy setup: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Manager review: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Company settings: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Users and roles: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Dashboard: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Transfer requests: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Workforce records: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Pay-item workflows: registers routes (evidence: `backend/app/main.py`)
- Payroll periods → Payroll calculation: uses calculation (evidence: `backend/app/payroll/period_lifecycle.py`)
- Review workspace → Manager review: loads snapshot and decides
- Payroll policy setup → Payroll workspace: provides policy
- API clients → FastAPI application: sends requests
- Workforce records → Payroll calculation: supplies workforce data
- Branch permissions → Workforce records: checks access (evidence: `backend/app/workforce/service.py`)