# baptchau/kronos architecture

> Architecture diagram of the GitHub repository baptchau/kronos, 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/baptchau/kronos
- Repository: https://github.com/baptchau/kronos

## Overview

Kronos is a multi-tenant time-tracking product: employees and company admins sign in, record work time, and review weekly entries and summaries; admins also manage employees and correct entries. Platform owners use a separate console to provision companies and manage cross-company accounts. The API routes requests into authentication, clock, timesheet, admin, and owner services backed by PostgreSQL. The README documents the product capabilities and frontends; edges between components are limited to relationships shown in excerpts or stated there.

Main entry points: [`backend/app/routers/admin.py`](https://github.com/baptchau/kronos/blob/main/backend/app/routers/admin.py) (Admin routes), [`backend/app/main.py`](https://github.com/baptchau/kronos/blob/main/backend/app/main.py) (FastAPI application), [`frontend/app`](https://github.com/baptchau/kronos/tree/main/frontend/app) (Employee app), [`backend/app/services/auth_service.py`](https://github.com/baptchau/kronos/blob/main/backend/app/services/auth_service.py) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User applications"]
  node_employee_app["Employee app"]
  node_clock_ui["Clock controls<br/>[ClockButton.tsx]"]
  node_timesheet_ui["Timesheet views<br/>[TimesheetTable.tsx]"]
  node_admin_ui["Company admin views"]
  node_owner_app["Owner console"]
  node_frontend_api["Employee API client<br/>[api.ts]"]
  node_owner_api["Owner API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_access_control["Authentication and roles<br/>[dependencies.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_auth_contracts["Auth contracts<br/>[auth.py]"]
end

subgraph group_work["Time tracking"]
  node_clock_routes["Clock routes<br/>[clock.py]"]
  node_clock_service["Clock service<br/>[clock_service.py]"]
  node_timesheet_routes["Timesheet routes<br/>[timesheet.py]"]
  node_timesheet_service["Timesheet service"]
  node_entry_contracts["Time entry contracts<br/>[time_entry.py]"]
end

subgraph group_tenancy["Company administration"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_owner_routes["Owner routes<br/>[owner.py]"]
  node_owner_service["Owner service<br/>[owner_service.py]"]
  node_user_contracts["User contracts<br/>[user.py]"]
end

subgraph group_persistence["Domain data"]
  node_company_model["Company model<br/>[company.py]"]
  node_user_model["User model<br/>[user.py]"]
  node_entry_model["Time entry model<br/>[time_entry.py]"]
  node_db_session["Database sessions<br/>[database.py]"]
end

node_employee(("Employee"))
node_company_admin(("Company admin"))
node_platform_owner(("Platform owner"))
node_postgres[("PostgreSQL")]

node_employee -->|"uses"| node_employee_app
node_company_admin -->|"uses"| node_employee_app
node_platform_owner -->|"uses"| node_owner_app
node_employee_app -->|"presents"| node_clock_ui
node_employee_app -->|"presents"| node_timesheet_ui
node_company_admin -->|"manages users"| node_admin_ui
node_admin_ui -->|"reviews entries"| node_timesheet_ui
node_employee_app -->|"requests"| node_frontend_api
node_frontend_api -->|"calls API"| node_api_app
node_owner_app -->|"requests"| node_owner_api
node_owner_api -->|"calls API"| node_api_app
node_api_app -->|"registers"| node_auth_routes
node_api_app -->|"registers"| node_clock_routes
node_api_app -->|"registers"| node_timesheet_routes
node_api_app -->|"registers"| node_admin_routes
node_api_app -->|"registers"| node_owner_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"validates"| node_auth_contracts
node_auth_routes -->|"uses"| node_access_control
node_clock_routes -->|"calls"| node_clock_service
node_clock_routes -->|"requires user"| node_access_control
node_timesheet_routes -->|"calls"| node_timesheet_service
node_timesheet_routes -->|"requires user"| node_access_control
node_timesheet_routes -->|"returns"| node_entry_contracts
node_admin_routes -->|"checks status"| node_clock_service
node_admin_routes -->|"calls"| node_timesheet_service
node_admin_routes -->|"checks users"| node_auth_service
node_admin_routes -->|"requires admin"| node_access_control
node_admin_routes -->|"returns"| node_user_contracts
node_admin_routes -->|"returns"| node_entry_contracts
node_owner_routes -->|"calls"| node_owner_service
node_owner_routes -->|"requires owner"| node_access_control
node_owner_service -->|"uses auth helpers"| node_auth_service
node_auth_service -->|"creates and queries"| node_company_model
node_auth_service -->|"authenticates"| node_user_model
node_clock_service -->|"operates on"| node_entry_model
node_timesheet_service -->|"queries and updates"| node_entry_model
node_owner_service -->|"creates and lists"| node_company_model
node_owner_service -->|"creates and lists"| node_user_model
node_db_session -->|"persists data"| node_postgres

click node_employee_app "https://github.com/baptchau/kronos/tree/main/frontend/app"
click node_clock_ui "https://github.com/baptchau/kronos/blob/main/frontend/components/ClockButton.tsx"
click node_timesheet_ui "https://github.com/baptchau/kronos/blob/main/frontend/components/TimesheetTable.tsx"
click node_admin_ui "https://github.com/baptchau/kronos/tree/main/frontend/app/admin"
click node_owner_app "https://github.com/baptchau/kronos/tree/main/frontend-owner/app"
click node_frontend_api "https://github.com/baptchau/kronos/blob/main/frontend/lib/api.ts"
click node_owner_api "https://github.com/baptchau/kronos/blob/main/frontend-owner/lib/api.ts"
click node_api_app "https://github.com/baptchau/kronos/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/baptchau/kronos/blob/main/backend/app/routers/auth.py"
click node_access_control "https://github.com/baptchau/kronos/blob/main/backend/app/dependencies.py"
click node_auth_service "https://github.com/baptchau/kronos/blob/main/backend/app/services/auth_service.py"
click node_auth_contracts "https://github.com/baptchau/kronos/blob/main/backend/app/schemas/auth.py"
click node_clock_routes "https://github.com/baptchau/kronos/blob/main/backend/app/routers/clock.py"
click node_clock_service "https://github.com/baptchau/kronos/blob/main/backend/app/services/clock_service.py"
click node_timesheet_routes "https://github.com/baptchau/kronos/blob/main/backend/app/routers/timesheet.py"
click node_timesheet_service "https://github.com/baptchau/kronos/blob/main/backend/app/services/timesheet_service.py"
click node_entry_contracts "https://github.com/baptchau/kronos/blob/main/backend/app/schemas/time_entry.py"
click node_admin_routes "https://github.com/baptchau/kronos/blob/main/backend/app/routers/admin.py"
click node_owner_routes "https://github.com/baptchau/kronos/blob/main/backend/app/routers/owner.py"
click node_owner_service "https://github.com/baptchau/kronos/blob/main/backend/app/services/owner_service.py"
click node_user_contracts "https://github.com/baptchau/kronos/blob/main/backend/app/schemas/user.py"
click node_company_model "https://github.com/baptchau/kronos/blob/main/backend/app/models/company.py"
click node_user_model "https://github.com/baptchau/kronos/blob/main/backend/app/models/user.py"
click node_entry_model "https://github.com/baptchau/kronos/blob/main/backend/app/models/time_entry.py"
click node_db_session "https://github.com/baptchau/kronos/blob/main/backend/app/database.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_employee_app,node_clock_ui,node_timesheet_ui,node_admin_ui,node_owner_app,node_frontend_api,node_owner_api toneBlue
class node_api_app,node_auth_routes,node_access_control,node_auth_service,node_auth_contracts,node_postgres toneAmber
class node_clock_routes,node_clock_service,node_timesheet_routes,node_timesheet_service,node_entry_contracts toneMint
class node_admin_routes,node_owner_routes,node_owner_service,node_user_contracts toneRose
class node_company_model,node_user_model,node_entry_model,node_db_session,node_employee,node_company_admin,node_platform_owner toneIndigo
```

## Components

### User applications

- [Employee app](https://github.com/baptchau/kronos/tree/main/frontend/app): `frontend/app`
- [Clock controls](https://github.com/baptchau/kronos/blob/main/frontend/components/ClockButton.tsx): `frontend/components/ClockButton.tsx`
- [Timesheet views](https://github.com/baptchau/kronos/blob/main/frontend/components/TimesheetTable.tsx): `frontend/components/TimesheetTable.tsx`
- [Company admin views](https://github.com/baptchau/kronos/tree/main/frontend/app/admin): `frontend/app/admin`
- [Owner console](https://github.com/baptchau/kronos/tree/main/frontend-owner/app): `frontend-owner/app`
- [Employee API client](https://github.com/baptchau/kronos/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Owner API client](https://github.com/baptchau/kronos/blob/main/frontend-owner/lib/api.ts): `frontend-owner/lib/api.ts`

### API and access

- [FastAPI application](https://github.com/baptchau/kronos/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/baptchau/kronos/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Authentication and roles](https://github.com/baptchau/kronos/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`
- [Auth service](https://github.com/baptchau/kronos/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Auth contracts](https://github.com/baptchau/kronos/blob/main/backend/app/schemas/auth.py): `backend/app/schemas/auth.py`

### Time tracking

- [Clock routes](https://github.com/baptchau/kronos/blob/main/backend/app/routers/clock.py): `backend/app/routers/clock.py`
- [Clock service](https://github.com/baptchau/kronos/blob/main/backend/app/services/clock_service.py): `backend/app/services/clock_service.py`
- [Timesheet routes](https://github.com/baptchau/kronos/blob/main/backend/app/routers/timesheet.py): `backend/app/routers/timesheet.py`
- [Timesheet service](https://github.com/baptchau/kronos/blob/main/backend/app/services/timesheet_service.py): `backend/app/services/timesheet_service.py`
- [Time entry contracts](https://github.com/baptchau/kronos/blob/main/backend/app/schemas/time_entry.py): `backend/app/schemas/time_entry.py`

### Company administration

- [Admin routes](https://github.com/baptchau/kronos/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [Owner routes](https://github.com/baptchau/kronos/blob/main/backend/app/routers/owner.py): `backend/app/routers/owner.py`
- [Owner service](https://github.com/baptchau/kronos/blob/main/backend/app/services/owner_service.py): `backend/app/services/owner_service.py`
- [User contracts](https://github.com/baptchau/kronos/blob/main/backend/app/schemas/user.py): `backend/app/schemas/user.py`

### Domain data

- [Company model](https://github.com/baptchau/kronos/blob/main/backend/app/models/company.py): `backend/app/models/company.py`
- [User model](https://github.com/baptchau/kronos/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Time entry model](https://github.com/baptchau/kronos/blob/main/backend/app/models/time_entry.py): `backend/app/models/time_entry.py`
- [Database sessions](https://github.com/baptchau/kronos/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Employee**
- **Company admin**
- **Platform owner**
- **PostgreSQL**

## Connections

- Employee → Employee app: uses
- Company admin → Employee app: uses
- Platform owner → Owner console: uses
- Employee app → Clock controls: presents
- Employee app → Timesheet views: presents
- Company admin → Company admin views: manages users
- Company admin views → Timesheet views: reviews entries
- Employee app → Employee API client: requests
- Employee API client → FastAPI application: calls API
- Owner console → Owner API client: requests
- Owner API client → FastAPI application: calls API
- FastAPI application → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Clock routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Timesheet routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Admin routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Owner routes: registers (evidence: `backend/app/main.py`)
- Authentication routes → Auth service: calls (evidence: `backend/app/routers/auth.py`)
- Authentication routes → Auth contracts: validates (evidence: `backend/app/routers/auth.py`)
- Authentication routes → Authentication and roles: uses (evidence: `backend/app/routers/auth.py`)
- Clock routes → Clock service: calls (evidence: `backend/app/routers/clock.py`)
- Clock routes → Authentication and roles: requires user (evidence: `backend/app/routers/clock.py`)
- Timesheet routes → Timesheet service: calls (evidence: `backend/app/routers/timesheet.py`)
- Timesheet routes → Authentication and roles: requires user (evidence: `backend/app/routers/timesheet.py`)
- Timesheet routes → Time entry contracts: returns (evidence: `backend/app/routers/timesheet.py`)
- Admin routes → Clock service: checks status (evidence: `backend/app/routers/admin.py`)
- Admin routes → Timesheet service: calls (evidence: `backend/app/routers/admin.py`)
- Admin routes → Auth service: checks users (evidence: `backend/app/routers/admin.py`)
- Admin routes → Authentication and roles: requires admin (evidence: `backend/app/routers/admin.py`)
- Admin routes → User contracts: returns (evidence: `backend/app/routers/admin.py`)
- Admin routes → Time entry contracts: returns (evidence: `backend/app/routers/admin.py`)
- Owner routes → Owner service: calls (evidence: `backend/app/routers/owner.py`)
- Owner routes → Authentication and roles: requires owner (evidence: `backend/app/routers/owner.py`)
- Owner service → Auth service: uses auth helpers (evidence: `backend/app/services/owner_service.py`)
- Auth service → Company model: creates and queries (evidence: `backend/app/services/auth_service.py`)
- Auth service → User model: authenticates (evidence: `backend/app/services/auth_service.py`)
- Clock service → Time entry model: operates on (evidence: `backend/app/services/clock_service.py`)
- Timesheet service → Time entry model: queries and updates (evidence: `backend/app/services/timesheet_service.py`)
- Owner service → Company model: creates and lists (evidence: `backend/app/services/owner_service.py`)
- Owner service → User model: creates and lists (evidence: `backend/app/services/owner_service.py`)
- Database sessions → PostgreSQL: persists data