# isorahmonov/stundenfassen architecture

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

- Interactive diagram: https://gitdiagram.com/isorahmonov/stundenfassen
- Repository: https://github.com/isorahmonov/stundenfassen

## Overview

This is a German-language shift, wage, and availability tracker. The main workflow records shifts for employers, stores them per user, and presents monthly aggregates, warnings, reconciliation, and exports. Separate screens manage planned shifts and calendar-based availability, including iCal feeds and an export archive; settings manage calendars and minus entries. The graph reflects documented imports and excerpted calls; several component implementations and API route bodies were not shown, so their internal connections are omitted.

Main entry points: [`app/components/MonatsUebersicht.tsx`](https://github.com/isorahmonov/stundenfassen/blob/main/app/components/MonatsUebersicht.tsx) (Monthly overview), [`lib/storage/index.ts`](https://github.com/isorahmonov/stundenfassen/blob/main/lib/storage/index.ts) (Repository access), [`app/verfuegbarkeit/page.tsx`](https://github.com/isorahmonov/stundenfassen/blob/main/app/verfuegbarkeit/page.tsx) (Availability screen), [`app/schichten/page.tsx`](https://github.com/isorahmonov/stundenfassen/blob/main/app/schichten/page.tsx) (Planned shifts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App screens"]
  node_monthly["Monthly overview"]
  node_employerui["Employer management"]
  node_shiftspage["Planned shifts<br/>[page.tsx]"]
  node_settings["Settings<br/>[page.tsx]"]
end

subgraph group_availability["Availability"]
  node_availabilitypage["Availability screen<br/>[page.tsx]"]
  node_icalapi["iCal API<br/>[route.ts]"]
  node_icalidapi["iCal feed route<br/>[route.ts]"]
  node_availabilitylogic["Availability logic<br/>[verfuegbarkeit.ts]"]
  node_icalparser["iCal parser<br/>[icalParser.ts]"]
  node_eventcache["Event selection cache<br/>[eventCache.ts]"]
  node_availabilityhelpers["Calendar helpers"]
  node_pdfavailability["Availability PDF"]
end

subgraph group_domain["Shift and wage domain"]
  node_shiftmodel["Shift and employer models<br/>[types.ts]"]
  node_aggregates["Monthly calculations<br/>[aggregate.ts]"]
  node_wagecalc["Wage calculations<br/>[lohn.ts]"]
  node_warnings["Shift warnings<br/>[warnings.ts]"]
  node_timecalc["Time calculations<br/>[time.ts]"]
  node_holidaycalc["Holiday and premiums<br/>[zuschlaege.ts]"]
  node_calcutils["Calculation helpers"]
end

subgraph group_persistence["Persistence"]
  node_storageapi["Repository access<br/>[index.ts]"]
  node_repos["Firestore repositories"]
  node_firestorehelpers["User-scoped mapping<br/>[shared.ts]"]
  node_firebaseclient["Firebase client<br/>[client.ts]"]
  node_firebaseadmin["Firebase admin<br/>[admin.ts]"]
  node_firestore[("Cloud Firestore")]
end

node_user(("Worker"))

node_user -->|"views"| node_monthly
node_user -->|"manages"| node_employerui
node_monthly -->|"calculates with"| node_aggregates
node_monthly -->|"loads data"| node_storageapi
node_monthly -->|"uses types"| node_shiftmodel
node_monthly -->|"formats results"| node_calcutils
node_aggregates -->|"calculates with"| node_wagecalc
node_aggregates -->|"checks shifts"| node_warnings
node_wagecalc -->|"uses"| node_timecalc
node_wagecalc -->|"uses"| node_holidaycalc
node_warnings -->|"uses"| node_timecalc
node_holidaycalc -->|"uses"| node_timecalc
node_shiftspage -->|"loads and edits"| node_storageapi
node_shiftspage -->|"uses week dates"| node_availabilityhelpers
node_shiftspage -->|"reads archive"| node_firestore
node_employerui -->|"manages employers"| node_storageapi
node_settings -->|"loads minus entries"| node_storageapi
node_settings -->|"requests calendars"| node_icalapi
node_availabilitypage -->|"calculates availability"| node_availabilitylogic
node_availabilitypage -->|"loads and saves selection"| node_eventcache
node_availabilitypage -->|"uses calendar helpers"| node_availabilityhelpers
node_availabilitypage -->|"archives exports"| node_firestore
node_icalapi -->|"uses"| node_firebaseadmin
node_icalapi -->|"parses feeds"| node_icalparser
node_icalidapi -->|"uses"| node_firebaseadmin
node_availabilitylogic -->|"parses calendar text"| node_icalparser
node_storageapi -->|"instantiates"| node_repos
node_repos -->|"uses mappings"| node_firestorehelpers
node_repos -->|"reads and writes"| node_firestore
node_firestorehelpers -->|"uses"| node_firebaseclient
node_firestorehelpers -->|"scopes user data"| node_firestore

click node_monthly "https://github.com/isorahmonov/stundenfassen/blob/main/app/components/MonatsUebersicht.tsx"
click node_employerui "https://github.com/isorahmonov/stundenfassen/blob/main/app/components/ArbeitgeberVerwaltung.tsx"
click node_shiftspage "https://github.com/isorahmonov/stundenfassen/blob/main/app/schichten/page.tsx"
click node_settings "https://github.com/isorahmonov/stundenfassen/blob/main/app/einstellungen/page.tsx"
click node_availabilitypage "https://github.com/isorahmonov/stundenfassen/blob/main/app/verfuegbarkeit/page.tsx"
click node_icalapi "https://github.com/isorahmonov/stundenfassen/blob/main/app/api/ical/route.ts"
click node_icalidapi "https://github.com/isorahmonov/stundenfassen/blob/main/app/api/ical/%5Bid%5D/route.ts"
click node_availabilitylogic "https://github.com/isorahmonov/stundenfassen/blob/main/lib/verfuegbarkeit/verfuegbarkeit.ts"
click node_icalparser "https://github.com/isorahmonov/stundenfassen/blob/main/lib/verfuegbarkeit/icalParser.ts"
click node_eventcache "https://github.com/isorahmonov/stundenfassen/blob/main/lib/verfuegbarkeit/eventCache.ts"
click node_availabilityhelpers "https://github.com/isorahmonov/stundenfassen/tree/main/lib/verfuegbarkeit"
click node_pdfavailability "https://github.com/isorahmonov/stundenfassen/blob/main/app/components/VerfuegbarkeitPDF.tsx"
click node_shiftmodel "https://github.com/isorahmonov/stundenfassen/blob/main/lib/types.ts"
click node_aggregates "https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/aggregate.ts"
click node_wagecalc "https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/lohn.ts"
click node_warnings "https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/warnings.ts"
click node_timecalc "https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/time.ts"
click node_holidaycalc "https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/zuschlaege.ts"
click node_calcutils "https://github.com/isorahmonov/stundenfassen/tree/main/lib/calc"
click node_storageapi "https://github.com/isorahmonov/stundenfassen/blob/main/lib/storage/index.ts"
click node_repos "https://github.com/isorahmonov/stundenfassen/tree/main/lib/storage/firestore"
click node_firestorehelpers "https://github.com/isorahmonov/stundenfassen/blob/main/lib/storage/firestore/shared.ts"
click node_firebaseclient "https://github.com/isorahmonov/stundenfassen/blob/main/lib/firebase/client.ts"
click node_firebaseadmin "https://github.com/isorahmonov/stundenfassen/blob/main/lib/firebase/admin.ts"

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_monthly,node_employerui,node_shiftspage,node_settings toneBlue
class node_availabilitypage,node_icalapi,node_icalidapi,node_availabilitylogic,node_icalparser,node_eventcache,node_availabilityhelpers,node_pdfavailability toneAmber
class node_shiftmodel,node_aggregates,node_wagecalc,node_warnings,node_timecalc,node_holidaycalc,node_calcutils toneMint
class node_storageapi,node_repos,node_firestorehelpers,node_firebaseclient,node_firebaseadmin,node_firestore,node_user toneRose
```

## Components

### App screens

- [Monthly overview](https://github.com/isorahmonov/stundenfassen/blob/main/app/components/MonatsUebersicht.tsx): `app/components/MonatsUebersicht.tsx`
- [Employer management](https://github.com/isorahmonov/stundenfassen/blob/main/app/components/ArbeitgeberVerwaltung.tsx): `app/components/ArbeitgeberVerwaltung.tsx`
- [Planned shifts](https://github.com/isorahmonov/stundenfassen/blob/main/app/schichten/page.tsx): `app/schichten/page.tsx`
- [Settings](https://github.com/isorahmonov/stundenfassen/blob/main/app/einstellungen/page.tsx): `app/einstellungen/page.tsx`

### Availability

- [Availability screen](https://github.com/isorahmonov/stundenfassen/blob/main/app/verfuegbarkeit/page.tsx): `app/verfuegbarkeit/page.tsx`
- [iCal API](https://github.com/isorahmonov/stundenfassen/blob/main/app/api/ical/route.ts): `app/api/ical/route.ts`
- [iCal feed route](https://github.com/isorahmonov/stundenfassen/blob/main/app/api/ical/%5Bid%5D/route.ts): `app/api/ical/[id]/route.ts`
- [Availability logic](https://github.com/isorahmonov/stundenfassen/blob/main/lib/verfuegbarkeit/verfuegbarkeit.ts): `lib/verfuegbarkeit/verfuegbarkeit.ts`
- [iCal parser](https://github.com/isorahmonov/stundenfassen/blob/main/lib/verfuegbarkeit/icalParser.ts): `lib/verfuegbarkeit/icalParser.ts`
- [Event selection cache](https://github.com/isorahmonov/stundenfassen/blob/main/lib/verfuegbarkeit/eventCache.ts): `lib/verfuegbarkeit/eventCache.ts`
- [Calendar helpers](https://github.com/isorahmonov/stundenfassen/tree/main/lib/verfuegbarkeit): `lib/verfuegbarkeit`
- [Availability PDF](https://github.com/isorahmonov/stundenfassen/blob/main/app/components/VerfuegbarkeitPDF.tsx): `app/components/VerfuegbarkeitPDF.tsx`

### Shift and wage domain

- [Shift and employer models](https://github.com/isorahmonov/stundenfassen/blob/main/lib/types.ts): `lib/types.ts`
- [Monthly calculations](https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/aggregate.ts): `lib/calc/aggregate.ts`
- [Wage calculations](https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/lohn.ts): `lib/calc/lohn.ts`
- [Shift warnings](https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/warnings.ts): `lib/calc/warnings.ts`
- [Time calculations](https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/time.ts): `lib/calc/time.ts`
- [Holiday and premiums](https://github.com/isorahmonov/stundenfassen/blob/main/lib/calc/zuschlaege.ts): `lib/calc/zuschlaege.ts`
- [Calculation helpers](https://github.com/isorahmonov/stundenfassen/tree/main/lib/calc): `lib/calc`

### Persistence

- [Repository access](https://github.com/isorahmonov/stundenfassen/blob/main/lib/storage/index.ts): `lib/storage/index.ts`
- [Firestore repositories](https://github.com/isorahmonov/stundenfassen/tree/main/lib/storage/firestore): `lib/storage/firestore`
- [User-scoped mapping](https://github.com/isorahmonov/stundenfassen/blob/main/lib/storage/firestore/shared.ts): `lib/storage/firestore/shared.ts`
- [Firebase client](https://github.com/isorahmonov/stundenfassen/blob/main/lib/firebase/client.ts): `lib/firebase/client.ts`
- [Firebase admin](https://github.com/isorahmonov/stundenfassen/blob/main/lib/firebase/admin.ts): `lib/firebase/admin.ts`
- **Cloud Firestore**

### Other components

- **Worker**

## Connections

- Worker → Monthly overview: views
- Worker → Employer management: manages
- Monthly overview → Monthly calculations: calculates with (evidence: `app/components/MonatsUebersicht.tsx`)
- Monthly overview → Repository access: loads data (evidence: `app/components/MonatsUebersicht.tsx`)
- Monthly overview → Shift and employer models: uses types (evidence: `app/components/MonatsUebersicht.tsx`)
- Monthly overview → Calculation helpers: formats results (evidence: `app/components/MonatsUebersicht.tsx`)
- Monthly calculations → Wage calculations: calculates with (evidence: `lib/calc/aggregate.ts`)
- Monthly calculations → Shift warnings: checks shifts (evidence: `lib/calc/aggregate.ts`)
- Wage calculations → Time calculations: uses (evidence: `lib/calc/lohn.ts`)
- Wage calculations → Holiday and premiums: uses (evidence: `lib/calc/lohn.ts`)
- Shift warnings → Time calculations: uses (evidence: `lib/calc/warnings.ts`)
- Holiday and premiums → Time calculations: uses (evidence: `lib/calc/zuschlaege.ts`)
- Planned shifts → Repository access: loads and edits (evidence: `app/schichten/page.tsx`)
- Planned shifts → Calendar helpers: uses week dates (evidence: `app/schichten/page.tsx`)
- Planned shifts → Cloud Firestore: reads archive (evidence: `app/schichten/page.tsx`)
- Employer management → Repository access: manages employers (evidence: `app/components/ArbeitgeberVerwaltung.tsx`)
- Settings → Repository access: loads minus entries (evidence: `app/einstellungen/page.tsx`)
- Settings → iCal API: requests calendars (evidence: `app/einstellungen/page.tsx`)
- Availability screen → Availability logic: calculates availability (evidence: `app/verfuegbarkeit/page.tsx`)
- Availability screen → Event selection cache: loads and saves selection (evidence: `app/verfuegbarkeit/page.tsx`)
- Availability screen → Calendar helpers: uses calendar helpers (evidence: `app/verfuegbarkeit/page.tsx`)
- Availability screen → Cloud Firestore: archives exports (evidence: `app/verfuegbarkeit/page.tsx`)
- iCal API → Firebase admin: uses (evidence: `app/api/ical/route.ts`)
- iCal API → iCal parser: parses feeds (evidence: `app/api/ical/route.ts`)
- iCal feed route → Firebase admin: uses (evidence: `app/api/ical/[id]/route.ts`)
- Availability logic → iCal parser: parses calendar text (evidence: `lib/verfuegbarkeit/verfuegbarkeit.ts`)
- Repository access → Firestore repositories: instantiates (evidence: `lib/storage/index.ts`)
- Firestore repositories → User-scoped mapping: uses mappings (evidence: `lib/storage/firestore/ShiftRepository.ts`)
- Firestore repositories → Cloud Firestore: reads and writes (evidence: `lib/storage/firestore/ShiftRepository.ts`)
- User-scoped mapping → Firebase client: uses (evidence: `lib/storage/firestore/shared.ts`)
- User-scoped mapping → Cloud Firestore: scopes user data (evidence: `lib/storage/firestore/shared.ts`)
