# lennystepn-hue/schichtplaner architecture

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

- Interactive diagram: https://gitdiagram.com/lennystepn-hue/schichtplaner
- Repository: https://github.com/lennystepn-hue/schichtplaner

## Overview

Schichtplaner is a self-hosted workforce-management application. The main workflow is a manager creating schedules and shifts, employees viewing schedules and booking shifts, and the application persisting changes and broadcasting live updates. Separate product areas handle employee and division administration, time records, absences, reporting, and the internal portal. AI assistance is an optional capability. The graph follows the supplied route excerpts and README; several feature connections are represented at directory level because their implementations were not sampled.

Main entry points: [`src/lib/db.ts`](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/db.ts) (Database access), [`src/lib/auth.ts`](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/auth.ts) (Authentication), [`src/lib/emit.ts`](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/emit.ts) (Real-time dispatch), [`src/app/api/shifts/route.ts`](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/shifts/route.ts) (Shifts API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Shift planning"]
  node_schedule_ui["Schedule views"]
  node_schedules_api["Schedules API<br/>[route.ts]"]
  node_shifts_api["Shifts API<br/>[route.ts]"]
  node_bookings_api["Bookings API<br/>[route.ts]"]
  node_wishes_api["Wish requests<br/>[route.ts]"]
end

subgraph group_workforce["Workforce operations"]
  node_employees_api["Employee management<br/>[route.ts]"]
  node_divisions_api["Division management"]
  node_time_api["Time tracking<br/>[route.ts]"]
  node_absences_api["Absence management<br/>[route.ts]"]
end

subgraph group_insights["Reporting and AI"]
  node_reports_api["Monthly reporting<br/>[route.ts]"]
  node_ai_api["AI capabilities"]
  node_ai_logic["AI services"]
end

subgraph group_portal["Internal portal"]
  node_messages_api["Messaging<br/>[route.ts]"]
  node_files_api["Portal files"]
  node_topics_api["Discussion topics"]
end

subgraph group_platform["Application platform"]
  node_settings_api["Organization settings<br/>[route.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_db_layer["Database access<br/>[db.ts]"]
  node_postgres[("PostgreSQL")]
  node_realtime["Real-time dispatch<br/>[emit.ts]"]
  node_socket_service["Socket.IO server<br/>[server.ts]"]
end

node_manager(("Manager"))
node_employee(("Employee"))
node_anthropic["Anthropic API"]
node_object_storage[("S3-compatible storage")]

node_manager -->|"plans shifts"| node_schedule_ui
node_employee -->|"views schedule"| node_schedule_ui
node_schedule_ui -->|"loads schedule"| node_schedules_api
node_schedules_api -->|"reads or creates"| node_db_layer
node_manager -->|"creates shifts"| node_shifts_api
node_shifts_api -->|"writes shifts"| node_db_layer
node_employee -->|"books shifts"| node_bookings_api
node_bookings_api -->|"writes bookings"| node_db_layer
node_employee -->|"requests shifts"| node_wishes_api
node_wishes_api -->|"reads and writes"| node_db_layer
node_manager -->|"manages staff"| node_employees_api
node_employees_api -->|"reads and writes"| node_db_layer
node_manager -->|"assigns divisions"| node_divisions_api
node_divisions_api -->|"reads and writes"| node_db_layer
node_employee -->|"records hours"| node_time_api
node_time_api -->|"reads and writes"| node_db_layer
node_employee -->|"requests leave"| node_absences_api
node_absences_api -->|"reads and writes"| node_db_layer
node_manager -->|"reviews hours"| node_reports_api
node_reports_api -->|"reads records"| node_db_layer
node_manager -.->|"requests assistance"| node_ai_api
node_ai_api -.->|"dispatches"| node_ai_logic
node_ai_logic -.->|"uses workforce data"| node_db_layer
node_ai_logic -.->|"calls model"| node_anthropic
node_employee -->|"messages colleagues"| node_messages_api
node_messages_api -->|"reads and writes"| node_db_layer
node_manager -->|"manages files"| node_files_api
node_files_api -->|"reads and writes metadata"| node_db_layer
node_files_api -.->|"stores uploads"| node_object_storage
node_employee -->|"joins discussions"| node_topics_api
node_topics_api -->|"reads and writes"| node_db_layer
node_manager -->|"configures organization"| node_settings_api
node_settings_api -->|"reads and writes"| node_db_layer
node_employees_api -->|"checks member"| node_auth
node_shifts_api -->|"checks member"| node_auth
node_bookings_api -->|"checks member"| node_auth
node_time_api -->|"checks member"| node_auth
node_absences_api -->|"checks member"| node_auth
node_reports_api -->|"checks member"| node_auth
node_messages_api -->|"checks member"| node_auth
node_db_layer -->|"queries"| node_postgres
node_bookings_api -->|"broadcasts changes"| node_realtime
node_shifts_api -->|"broadcasts changes"| node_realtime
node_messages_api -->|"broadcasts notices"| node_realtime
node_wishes_api -->|"broadcasts changes"| node_realtime
node_realtime -->|"dispatches events"| node_socket_service

click node_schedule_ui "https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/(dashboard)/schedule"
click node_schedules_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/schedules/route.ts"
click node_shifts_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/shifts/route.ts"
click node_bookings_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/bookings/route.ts"
click node_wishes_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/mod-requests/route.ts"
click node_employees_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/employees/route.ts"
click node_divisions_api "https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/divisions"
click node_time_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/time/route.ts"
click node_absences_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/absences/route.ts"
click node_reports_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/reporting/route.ts"
click node_ai_api "https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/ai"
click node_ai_logic "https://github.com/lennystepn-hue/schichtplaner/tree/master/src/lib/ai"
click node_messages_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/messages/route.ts"
click node_files_api "https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/files"
click node_topics_api "https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/topics"
click node_settings_api "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/settings/route.ts"
click node_auth "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/auth.ts"
click node_db_layer "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/db.ts"
click node_realtime "https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/emit.ts"
click node_socket_service "https://github.com/lennystepn-hue/schichtplaner/blob/master/server.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_schedule_ui,node_schedules_api,node_shifts_api,node_bookings_api,node_wishes_api toneBlue
class node_employees_api,node_divisions_api,node_time_api,node_absences_api,node_object_storage toneAmber
class node_reports_api,node_ai_api,node_ai_logic,node_anthropic toneMint
class node_messages_api,node_files_api,node_topics_api toneRose
class node_settings_api,node_auth,node_db_layer,node_postgres,node_realtime,node_socket_service,node_manager,node_employee toneIndigo
```

## Components

### Shift planning

- [Schedule views](https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/(dashboard)/schedule): `src/app/(dashboard)/schedule`
- [Schedules API](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/schedules/route.ts): `src/app/api/schedules/route.ts`
- [Shifts API](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/shifts/route.ts): `src/app/api/shifts/route.ts`
- [Bookings API](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/bookings/route.ts): `src/app/api/bookings/route.ts`
- [Wish requests](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/mod-requests/route.ts): `src/app/api/mod-requests/route.ts`

### Workforce operations

- [Employee management](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/employees/route.ts): `src/app/api/employees/route.ts`
- [Division management](https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/divisions): `src/app/api/divisions`
- [Time tracking](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/time/route.ts): `src/app/api/time/route.ts`
- [Absence management](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/absences/route.ts): `src/app/api/absences/route.ts`

### Reporting and AI

- [Monthly reporting](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/reporting/route.ts): `src/app/api/reporting/route.ts`
- [AI capabilities](https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/ai): `src/app/api/ai`
- [AI services](https://github.com/lennystepn-hue/schichtplaner/tree/master/src/lib/ai): `src/lib/ai`

### Internal portal

- [Messaging](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/messages/route.ts): `src/app/api/messages/route.ts`
- [Portal files](https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/files): `src/app/api/files`
- [Discussion topics](https://github.com/lennystepn-hue/schichtplaner/tree/master/src/app/api/topics): `src/app/api/topics`

### Application platform

- [Organization settings](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/app/api/settings/route.ts): `src/app/api/settings/route.ts`
- [Authentication](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/auth.ts): `src/lib/auth.ts`
- [Database access](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/db.ts): `src/lib/db.ts`
- **PostgreSQL**
- [Real-time dispatch](https://github.com/lennystepn-hue/schichtplaner/blob/master/src/lib/emit.ts): `src/lib/emit.ts`
- [Socket.IO server](https://github.com/lennystepn-hue/schichtplaner/blob/master/server.ts): `server.ts`

### Other components

- **Manager**
- **Employee**
- **Anthropic API**
- **S3-compatible storage**

## Connections

- Manager → Schedule views: plans shifts
- Employee → Schedule views: views schedule
- Schedule views → Schedules API: loads schedule
- Schedules API → Database access: reads or creates
- Manager → Shifts API: creates shifts
- Shifts API → Database access: writes shifts
- Employee → Bookings API: books shifts
- Bookings API → Database access: writes bookings
- Employee → Wish requests: requests shifts
- Wish requests → Database access: reads and writes
- Manager → Employee management: manages staff
- Employee management → Database access: reads and writes
- Manager → Division management: assigns divisions
- Division management → Database access: reads and writes
- Employee → Time tracking: records hours
- Time tracking → Database access: reads and writes
- Employee → Absence management: requests leave
- Absence management → Database access: reads and writes
- Manager → Monthly reporting: reviews hours
- Monthly reporting → Database access: reads records
- Manager → AI capabilities: requests assistance
- AI capabilities → AI services: dispatches
- AI services → Database access: uses workforce data
- AI services → Anthropic API: calls model
- Employee → Messaging: messages colleagues
- Messaging → Database access: reads and writes
- Manager → Portal files: manages files
- Portal files → Database access: reads and writes metadata
- Portal files → S3-compatible storage: stores uploads
- Employee → Discussion topics: joins discussions
- Discussion topics → Database access: reads and writes
- Manager → Organization settings: configures organization
- Organization settings → Database access: reads and writes
- Employee management → Authentication: checks member
- Shifts API → Authentication: checks member
- Bookings API → Authentication: checks member
- Time tracking → Authentication: checks member
- Absence management → Authentication: checks member
- Monthly reporting → Authentication: checks member
- Messaging → Authentication: checks member
- Database access → PostgreSQL: queries
- Bookings API → Real-time dispatch: broadcasts changes
- Shifts API → Real-time dispatch: broadcasts changes
- Messaging → Real-time dispatch: broadcasts notices
- Wish requests → Real-time dispatch: broadcasts changes
- Real-time dispatch → Socket.IO server: dispatches events