# treuware/timesheet-saas architecture

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

- Interactive diagram: https://gitdiagram.com/treuware/timesheet-saas
- Repository: https://github.com/treuware/timesheet-saas

## Overview

Timesheet SaaS is a multi-tenant scheduling and time-tracking product for small businesses, with a separate platform-operator surface. The tenant workflow covers workforce setup, shift planning, attendance and breaks, timesheet approval, and accounting export; configurable working-time law supports mandatory-break evaluation. Platform operators manage tenants, plans, subscriptions, support, settings, and audit. The tree and README establish capabilities; sampled source also shows attendance invoking timesheet services and contract operations using legal/agreement services. Other links are included only where documented or indexed; unsampled internals are not assumed.

Main entry points: [`backend/app/main.py`](https://github.com/treuware/timesheet-saas/blob/main/backend/app/main.py) (API entry), [`backend/app/modules/employee/models.py`](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/employee/models.py) (Employees and contracts), [`backend/app/modules/shift/router.py`](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/shift/router.py) (Shift planning), [`backend/app/modules/attendance/router.py`](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/attendance/router.py) (Attendance and breaks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tenant_access["Tenant access"]
  node_web_app["Tenant web app<br/>[App.tsx]"]
  node_tenant_auth["Tenant authentication<br/>[router.py]"]
  node_api_entry["API entry<br/>[main.py]"]
end

subgraph group_workforce_planning["Workforce planning"]
  node_company_branch[("Companies and branches<br/>[models.py]")]
  node_employees[("Employees and contracts<br/>[models.py]")]
  node_availability["Weekly availability"]
  node_shift_planning["Shift planning<br/>[router.py]"]
  node_planner_advisory["Planner advisory"]
end

subgraph group_time_payroll["Time and payroll"]
  node_attendance["Attendance and breaks<br/>[router.py]"]
  node_timesheets["Timesheet review<br/>[service.py]"]
  node_accounting_export["Accounting export<br/>[service.py]"]
  node_dashboard["Business dashboard"]
end

subgraph group_rules_compliance["Rules and compliance"]
  node_legal_config["Legal configuration<br/>[service.py]"]
  node_agreements["Collective agreements<br/>[service.py]"]
  node_policy_resolution["Working-time policy<br/>[service.py]"]
  node_rule_engine["Rule resolution<br/>[resolver.py]"]
  node_legal_evaluation["Break evaluation<br/>[service.py]"]
end

subgraph group_platform_ops["Platform operations"]
  node_platform_app["Operator web app<br/>[PlatformApp.tsx]"]
  node_platform_auth["Operator authentication<br/>[router.py]"]
  node_tenant_admin["Tenant lifecycle<br/>[service.py]"]
  node_commercial_admin["Plans and subscriptions<br/>[service.py]"]
  node_platform_services["Operator services<br/>[service.py]"]
  node_platform_email["Account email actions<br/>[account_routes.py]"]
end

node_business_user(("Business user"))

node_business_user -->|"uses"| node_web_app
node_web_app -.->|"uses API"| node_api_entry
node_api_entry -->|"mounts routes"| node_tenant_auth
node_api_entry -->|"mounts routes"| node_attendance
node_api_entry -->|"mounts routes"| node_shift_planning
node_api_entry -->|"mounts routes"| node_planner_advisory
node_api_entry -->|"mounts routes"| node_legal_evaluation
node_business_user -->|"sets up"| node_company_branch
node_business_user -->|"manages workforce"| node_employees
node_business_user -->|"sets availability"| node_availability
node_business_user -->|"plans shifts"| node_shift_planning
node_business_user -->|"records work"| node_attendance
node_attendance -->|"calls service"| node_timesheets
node_business_user -->|"approves months"| node_timesheets
node_business_user -->|"exports records"| node_accounting_export
node_business_user -->|"views evaluation"| node_legal_evaluation
node_business_user -->|"configures law"| node_legal_config
node_shift_planning -->|"reads coverage"| node_employees
node_shift_planning -->|"reads branches"| node_company_branch
node_employees -->|"assigns agreement"| node_agreements
node_employees -->|"checks regimes"| node_legal_config
node_policy_resolution -->|"uses combination"| node_rule_engine
node_business_user -->|"uses"| node_platform_app
node_platform_app -.->|"uses API"| node_platform_auth
node_platform_auth -.->|"account actions"| node_platform_email
node_business_user -->|"operator manages tenants"| node_tenant_admin
node_business_user -->|"operator manages plans"| node_commercial_admin
node_business_user -->|"operator handles support"| node_platform_services

click node_web_app "https://github.com/treuware/timesheet-saas/blob/main/frontend/src/App.tsx"
click node_tenant_auth "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/auth/router.py"
click node_api_entry "https://github.com/treuware/timesheet-saas/blob/main/backend/app/main.py"
click node_company_branch "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/company/models.py"
click node_employees "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/employee/models.py"
click node_availability "https://github.com/treuware/timesheet-saas/tree/main/backend/app/modules/availability"
click node_shift_planning "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/shift/router.py"
click node_planner_advisory "https://github.com/treuware/timesheet-saas/tree/main/backend/app/modules/advisory"
click node_attendance "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/attendance/router.py"
click node_timesheets "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/timesheet/service.py"
click node_accounting_export "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/export/service.py"
click node_dashboard "https://github.com/treuware/timesheet-saas/tree/main/backend/app/modules/dashboard"
click node_legal_config "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/legal/service.py"
click node_agreements "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/collective_agreement/service.py"
click node_policy_resolution "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/working_time_policy/service.py"
click node_rule_engine "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/rule_resolution/resolver.py"
click node_legal_evaluation "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/legal_evaluation/service.py"
click node_platform_app "https://github.com/treuware/timesheet-saas/blob/main/frontend/src/platform/PlatformApp.tsx"
click node_platform_auth "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_auth/router.py"
click node_tenant_admin "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_tenants/service.py"
click node_commercial_admin "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_subscriptions/service.py"
click node_platform_services "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_support/service.py"
click node_platform_email "https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_email/account_routes.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_app,node_tenant_auth,node_api_entry,node_business_user toneBlue
class node_company_branch,node_employees,node_availability,node_shift_planning,node_planner_advisory toneAmber
class node_attendance,node_timesheets,node_accounting_export,node_dashboard toneMint
class node_legal_config,node_agreements,node_policy_resolution,node_rule_engine,node_legal_evaluation toneRose
class node_platform_app,node_platform_auth,node_tenant_admin,node_commercial_admin,node_platform_services,node_platform_email toneIndigo
```

## Components

### Tenant access

- [Tenant web app](https://github.com/treuware/timesheet-saas/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Tenant authentication](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/auth/router.py): `backend/app/modules/auth/router.py`
- [API entry](https://github.com/treuware/timesheet-saas/blob/main/backend/app/main.py): `backend/app/main.py`

### Workforce planning

- [Companies and branches](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/company/models.py): `backend/app/modules/company/models.py`
- [Employees and contracts](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/employee/models.py): `backend/app/modules/employee/models.py`
- [Weekly availability](https://github.com/treuware/timesheet-saas/tree/main/backend/app/modules/availability): `backend/app/modules/availability`
- [Shift planning](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/shift/router.py): `backend/app/modules/shift/router.py`
- [Planner advisory](https://github.com/treuware/timesheet-saas/tree/main/backend/app/modules/advisory): `backend/app/modules/advisory`

### Time and payroll

- [Attendance and breaks](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/attendance/router.py): `backend/app/modules/attendance/router.py`
- [Timesheet review](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/timesheet/service.py): `backend/app/modules/timesheet/service.py`
- [Accounting export](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/export/service.py): `backend/app/modules/export/service.py`
- [Business dashboard](https://github.com/treuware/timesheet-saas/tree/main/backend/app/modules/dashboard): `backend/app/modules/dashboard`

### Rules and compliance

- [Legal configuration](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/legal/service.py): `backend/app/modules/legal/service.py`
- [Collective agreements](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/collective_agreement/service.py): `backend/app/modules/collective_agreement/service.py`
- [Working-time policy](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/working_time_policy/service.py): `backend/app/modules/working_time_policy/service.py`
- [Rule resolution](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/rule_resolution/resolver.py): `backend/app/modules/rule_resolution/resolver.py`
- [Break evaluation](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/legal_evaluation/service.py): `backend/app/modules/legal_evaluation/service.py`

### Platform operations

- [Operator web app](https://github.com/treuware/timesheet-saas/blob/main/frontend/src/platform/PlatformApp.tsx): `frontend/src/platform/PlatformApp.tsx`
- [Operator authentication](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_auth/router.py): `backend/app/modules/platform_auth/router.py`
- [Tenant lifecycle](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_tenants/service.py): `backend/app/modules/platform_tenants/service.py`
- [Plans and subscriptions](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_subscriptions/service.py): `backend/app/modules/platform_subscriptions/service.py`
- [Operator services](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_support/service.py): `backend/app/modules/platform_support/service.py`
- [Account email actions](https://github.com/treuware/timesheet-saas/blob/main/backend/app/modules/platform_email/account_routes.py): `backend/app/modules/platform_email/account_routes.py`

### Other components

- **Business user**

## Connections

- Business user → Tenant web app: uses (evidence: `README.md`)
- Tenant web app → API entry: uses API
- API entry → Tenant authentication: mounts routes (evidence: `backend/app/main.py`)
- API entry → Attendance and breaks: mounts routes (evidence: `backend/app/main.py`)
- API entry → Shift planning: mounts routes (evidence: `backend/app/main.py`)
- API entry → Planner advisory: mounts routes (evidence: `backend/app/main.py`)
- API entry → Break evaluation: mounts routes (evidence: `backend/app/main.py`)
- Business user → Companies and branches: sets up (evidence: `README.md`)
- Business user → Employees and contracts: manages workforce (evidence: `README.md`)
- Business user → Weekly availability: sets availability (evidence: `README.md`)
- Business user → Shift planning: plans shifts (evidence: `README.md`)
- Business user → Attendance and breaks: records work (evidence: `README.md`)
- Attendance and breaks → Timesheet review: calls service (evidence: `backend/app/modules/attendance/router.py`)
- Business user → Timesheet review: approves months (evidence: `README.md`)
- Business user → Accounting export: exports records (evidence: `README.md`)
- Business user → Break evaluation: views evaluation (evidence: `README.md`)
- Business user → Legal configuration: configures law (evidence: `README.md`)
- Shift planning → Employees and contracts: reads coverage (evidence: `backend/app/modules/shift/router.py`)
- Shift planning → Companies and branches: reads branches (evidence: `backend/app/modules/shift/router.py`)
- Employees and contracts → Collective agreements: assigns agreement (evidence: `backend/app/modules/contract/router.py`)
- Employees and contracts → Legal configuration: checks regimes
- Working-time policy → Rule resolution: uses combination (evidence: `backend/app/modules/working_time_policy/service.py`)
- Business user → Operator web app: uses (evidence: `README.md`)
- Operator web app → Operator authentication: uses API
- Operator authentication → Account email actions: account actions
- Business user → Tenant lifecycle: operator manages tenants (evidence: `README.md`)
- Business user → Plans and subscriptions: operator manages plans (evidence: `README.md`)
- Business user → Operator services: operator handles support (evidence: `README.md`)
