# eporsche/daybreak architecture

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

- Interactive diagram: https://gitdiagram.com/eporsche/daybreak
- Repository: https://github.com/eporsche/daybreak

## Overview

1. **Overall shape**
   - Daybreak is a **single Laravel monolith** for small-business timesheets and vacation planning.
   - The app is organized around a few core business domains: **accounts, locations, employees, time tracking, absences/vacation, public holidays, and reporting**.

2. **Technology stack that matters architecturally**
   - Backend is **PHP/Laravel**.
   - UI is built with **Blade + Livewire**, with **Jetstream/Fortify** handling auth, profile, teams-like account structure, API tokens, and two-factor flows.
   - Front-end assets use **Laravel Mix/Webpack, Tailwind, and compiled JS/CSS**.
   - Background work uses **Laravel jobs/queue** and **artisan console commands**.

3. **Primary request entry points**
   - Browser traffic enters through `routes/web.php` and is routed into **thin controllers** and **Livewire components**.
   - `routes/api.php` exists, but the repo is mostly oriented around server-rendered/admin workflows rather than a standalone public API.
   - Middleware such as `EnsureUserHasCurrentLocation` indicates a key boundary: many actions are only valid in the context of a selected **current location**.

4. **Domain boundaries**
   - **Account**: top-level tenant-like container for users and locations.
   - **Location**: operational unit where working time, absences, holidays, and settings belong.
   - **Employee/User**: people assigned to accounts and locations, with role-based access.
   - **Time tracking**: punch-in/out and pause handling.
   - **Absences/Vacations**: leave requests, approval, entitlement tracking, bans, and calendar rendering.
   - **Public holidays**: location-specific holiday data, imported and maintained separately.
   - **Reports**: aggregated period-based evaluation of time and absence data.

5. **Business logic is concentrated in action classes**
   - The `app/Actions` folder contains use-case-oriented services such as:
     - adding/removing/updating **locations**, **members**, **time trackings**, **absences**, **vacation entitlements**, **public holidays**, and **target hours**
     - approving absences
     - importing holidays
     - deleting accounts and locations
   - These actions are paired with `app/Contracts`, which define the behavior expected by controllers/Livewire components. This creates a clear **presentation → use case → model** boundary.

6. **Persistence model and relationships**
   - The system uses **Eloquent models** for all major entities: `Account`, `Location`, `User`, `TimeTracking`, `Absence`, `AbsenceType`, `PublicHoliday`, `TargetHour`, `VacationEntitlement`, `VacationBan`, `WorkingSession`, and related pivot/association tables.
   - The migrations show a multi-tenant relational structure with **pivot tables for memberships and type assignments**, plus dedicated tables for pause times, absence indexes, and working session actions.
   - Custom casts and rules (`DurationCast`, `BigDecimalCast`, `WeekDayCast`) indicate the domain stores time and duration with special precision handling.

7. **Time tracking subsystem**
   - Time tracking is not just CRUD; it has its own **state machine** in `app/StateMachine/WorkingSession`.
   - Working sessions move through **Running, Paused, and Stopped** states via explicit transitions.
   - `WorkingSessionToTimeTracking` converts state/session data into persisted `TimeTracking` records.
   - There is also logic for **pause-time calculation**, including a console command to recalculate pause times and a `DefaultRestingTime` concept that can be assigned per location/user.

8. **Absence and vacation subsystem**
   - Absence management has its own subsystem with:
     - `AbsenceCalendar` classes for day-by-day rendering
     - `AbsenceCalculator` for calculating absence effects
     - `AbsenceType` and user assignment
     - `VacationEntitlement`, `VacationBan`, and entitlement transfers
   - Approval is a distinct workflow: absences can be created, approved, removed, and trigger notifications.
   - This subsystem is tightly tied to location calendars and target-hour calculations.

9. **Reporting and calendar generation**
   - Reporting is handled by dedicated report classes: `ReportBuilder`, `ReportRowBuilder`, and `StartBalanceRowBuilder`.
   - `PeriodCalculator` and `HasPeriod` traits suggest reports operate over configurable date ranges.
   - Calendar views exist for both locations and employees, so the app presents **time/absence data in calendar form** as well as in tabular reports.

10. **Notifications, jobs, and external integrations**
   - Mail is used for operational events such as:
     - location invitations
     - new absence waiting for approval
     - absence approved/removed
   - Queue jobs exist for tasks like **sending approval emails** and **expiring vacation entitlements**.
   - Public holidays are imported via a dedicated holiday client and related import action, indicating an external data source for holiday rules.

11. **Auth, permissions, and tenancy boundaries**
   - Authentication and account management rely on **Fortify/Jetstream** plus policies in `app/Policies`.
   - Policies are defined for accounts, locations, absences, time tracking, reports, and users, so authorization is enforced at the domain boundary rather than inside views.
   - Current location selection is enforced through middleware and used by many domain actions, which means the app behaves like a **location-scoped workspace** inside an account.

12. **Operational/deployment shape**
   - The repo includes a `Procfile`, Heroku workflow, and Docker/Sail setup, so it can run as a **containerized Laravel app** or be deployed to Heroku.
   - Feature tests cover the main business flows, which is important because the architecture is heavily centered on domain rules rather than simple page rendering.

Main entry points: [`app/Models`](https://github.com/eporsche/daybreak/tree/master/app/Models) (Eloquent models), [`app/Actions`](https://github.com/eporsche/daybreak/tree/master/app/Actions) (Use-case actions), [`app/Providers/FortifyServiceProvider.php`](https://github.com/eporsche/daybreak/blob/master/app/Providers/FortifyServiceProvider.php) (Auth & tenancy), [`routes/web.php`](https://github.com/eporsche/daybreak/blob/master/routes/web.php) (Web routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Entry & UI"]
  node_n1["Web routes<br/>routing<br/>[web.php]"]
  node_n2["API routes<br/>routing<br/>[api.php]"]
  node_n3["HTTP controllers"]
  node_n4["Livewire UI<br/>components"]
  node_n5["Blade views<br/>templates"]
end

subgraph group_g2["Domain Core"]
  node_n6["Use-case actions<br/>application services"]
  node_n7["Action contracts<br/>ports"]
  node_n8[("Eloquent models<br/>persistence models")]
  node_n9["Domain traits<br/>shared logic"]
end

subgraph group_g3["Time & Absence"]
  node_n10{{"Time sessions<br/>time tracking subsystem"}}
  node_n11["Pause timing<br/>calculation"]
  node_n12["Absence calendar<br/>absence subsystem"]
  node_n13["Vacation rules<br/>absence policy"]
  node_n14["Public holidays<br/>holiday integration"]
  node_n15["Reports<br/>period reporting"]
end

subgraph group_g4["Platform"]
  node_n16["Auth & tenancy<br/>platform services"]
  node_n17["Middleware<br/>request boundary"]
  node_n18["Jobs & mail<br/>async notifications"]
  node_n19["Console & queue<br/>runtime"]
  node_n20["Build assets<br/>frontend build<br/>[webpack.mix.js]"]
end

node_n1 -->|"dispatches"| node_n3
node_n1 -->|"mounts"| node_n4
node_n1 -->|"protected by"| node_n16
node_n2 -.->|"protected by"| node_n16
node_n3 -->|"calls"| node_n6
node_n4 -->|"calls"| node_n6
node_n4 -->|"renders"| node_n5
node_n3 -->|"returns views"| node_n5
node_n6 -->|"implements"| node_n7
node_n6 -->|"persists via"| node_n8
node_n8 -.->|"uses"| node_n9
node_n10 -->|"writes"| node_n8
node_n10 -->|"feeds"| node_n11
node_n11 -->|"updates"| node_n8
node_n12 -->|"depends on"| node_n13
node_n13 -->|"stores in"| node_n8
node_n14 -->|"imports via"| node_n6
node_n14 -->|"stores in"| node_n8
node_n15 -->|"reads"| node_n8
node_n15 -.->|"filters via"| node_n6
node_n17 -->|"enforces"| node_n16
node_n18 -->|"notifies"| node_n16
node_n19 -->|"runs"| node_n11
node_n20 -.->|"supplies assets"| node_n5

click node_n1 "https://github.com/eporsche/daybreak/blob/master/routes/web.php"
click node_n2 "https://github.com/eporsche/daybreak/blob/master/routes/api.php"
click node_n3 "https://github.com/eporsche/daybreak/tree/master/app/Http/Controllers"
click node_n4 "https://github.com/eporsche/daybreak/tree/master/app/Http/Livewire"
click node_n5 "https://github.com/eporsche/daybreak/tree/master/resources/views"
click node_n6 "https://github.com/eporsche/daybreak/tree/master/app/Actions"
click node_n7 "https://github.com/eporsche/daybreak/tree/master/app/Contracts"
click node_n8 "https://github.com/eporsche/daybreak/tree/master/app/Models"
click node_n9 "https://github.com/eporsche/daybreak/tree/master/app/Traits"
click node_n10 "https://github.com/eporsche/daybreak/tree/master/app/StateMachine/WorkingSession"
click node_n11 "https://github.com/eporsche/daybreak/blob/master/app/Console/Commands/RecalculatePauseTimes.php"
click node_n12 "https://github.com/eporsche/daybreak/tree/master/app/AbsenceCalendar"
click node_n13 "https://github.com/eporsche/daybreak/blob/master/app/Models/VacationEntitlement.php"
click node_n14 "https://github.com/eporsche/daybreak/tree/master/app/Holiday"
click node_n15 "https://github.com/eporsche/daybreak/tree/master/app/Report"
click node_n16 "https://github.com/eporsche/daybreak/blob/master/app/Providers/FortifyServiceProvider.php"
click node_n17 "https://github.com/eporsche/daybreak/tree/master/app/Http/Middleware"
click node_n18 "https://github.com/eporsche/daybreak/tree/master/app/Jobs"
click node_n19 "https://github.com/eporsche/daybreak/tree/master/app/Console"
click node_n20 "https://github.com/eporsche/daybreak/blob/master/webpack.mix.js"

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_n1,node_n2,node_n3,node_n4,node_n5 toneBlue
class node_n6,node_n7,node_n8,node_n9 toneAmber
class node_n10,node_n11,node_n12,node_n13,node_n14,node_n15 toneMint
class node_n16,node_n17,node_n18,node_n19,node_n20 toneRose
```

## Components

### Entry & UI

Browser entrypoints, routing, controllers, Livewire, and Blade views.

- [Web routes](https://github.com/eporsche/daybreak/blob/master/routes/web.php): routing · Primary browser entrypoint for the monolith. · `routes/web.php`
- [API routes](https://github.com/eporsche/daybreak/blob/master/routes/api.php): routing · Secondary API entrypoint used sparingly. · `routes/api.php`
- [HTTP controllers](https://github.com/eporsche/daybreak/tree/master/app/Http/Controllers): controllers · Thin request handlers for account, location, time, absence, and reports. · `app/Http/Controllers`
- [Livewire UI](https://github.com/eporsche/daybreak/tree/master/app/Http/Livewire): components · Interactive server-rendered screens for core workflows. · `app/Http/Livewire`
- [Blade views](https://github.com/eporsche/daybreak/tree/master/resources/views): templates · Rendered pages, layouts, and mail templates. · `resources/views`

### Domain Core

Business actions, contracts, models, and supporting domain services.

- [Use-case actions](https://github.com/eporsche/daybreak/tree/master/app/Actions): application services · Domain operations for creating, updating, approving, importing, and deleting. · `app/Actions`
- [Action contracts](https://github.com/eporsche/daybreak/tree/master/app/Contracts): ports · Interfaces that define expected use-case behavior. · `app/Contracts`
- [Eloquent models](https://github.com/eporsche/daybreak/tree/master/app/Models): persistence models · Core tenant, location, employee, time, absence, and entitlement entities. · `app/Models`
- [Domain traits](https://github.com/eporsche/daybreak/tree/master/app/Traits): shared logic · Reusable query and relation behavior across models and reports. · `app/Traits`

### Time & Absence

Specialized subsystems for time tracking, absence management, holidays, and reports.

- [Time sessions](https://github.com/eporsche/daybreak/tree/master/app/StateMachine/WorkingSession): time tracking subsystem · Working-session state machine and conversion into persisted tracking records. · `app/StateMachine/WorkingSession`
- [Pause timing](https://github.com/eporsche/daybreak/blob/master/app/Console/Commands/RecalculatePauseTimes.php): calculation · Pause-time calculation, resting-time rules, and recalculation command. · `app/Console/Commands/RecalculatePauseTimes.php`
- [Absence calendar](https://github.com/eporsche/daybreak/tree/master/app/AbsenceCalendar): absence subsystem · Calendar rendering and absence calculation for day-by-day planning. · `app/AbsenceCalendar`
- [Vacation rules](https://github.com/eporsche/daybreak/blob/master/app/Models/VacationEntitlement.php): absence policy · Entitlements, bans, transfers, and approval workflow for leave. · `app/Models/VacationEntitlement.php`
- [Public holidays](https://github.com/eporsche/daybreak/tree/master/app/Holiday): holiday integration · Holiday client, import action, and location-specific holiday data. · `app/Holiday`
- [Reports](https://github.com/eporsche/daybreak/tree/master/app/Report): period reporting · Period-based evaluation and report row building. · `app/Report`

### Platform

Auth, middleware, queue, console, and deployment/runtime support.

- [Auth & tenancy](https://github.com/eporsche/daybreak/blob/master/app/Providers/FortifyServiceProvider.php): platform services · Fortify/Jetstream, policies, and current-location enforcement. · `app/Providers/FortifyServiceProvider.php`
- [Middleware](https://github.com/eporsche/daybreak/tree/master/app/Http/Middleware): request boundary · Request filters including current-location enforcement and auth/session guards. · `app/Http/Middleware`
- [Jobs & mail](https://github.com/eporsche/daybreak/tree/master/app/Jobs): async notifications · Queued jobs and operational email notifications. · `app/Jobs`
- [Console & queue](https://github.com/eporsche/daybreak/tree/master/app/Console): runtime · Artisan kernel and command scheduling/execution. · `app/Console`
- [Build assets](https://github.com/eporsche/daybreak/blob/master/webpack.mix.js): frontend build · Compiled frontend assets and bundling setup. · `webpack.mix.js`

## Connections

- Web routes → HTTP controllers: dispatches · Web requests are handled by controllers.
- Web routes → Livewire UI: mounts · Some routes render Livewire-driven pages.
- Web routes → Auth & tenancy: protected by · Authentication and tenancy context gate browser flows.
- API routes → Auth & tenancy: protected by · API access is still subject to auth and policies.
- HTTP controllers → Use-case actions: calls · Controllers delegate business operations to actions.
- Livewire UI → Use-case actions: calls · Livewire components invoke use-case actions.
- Livewire UI → Blade views: renders · Livewire components use Blade views and layouts.
- HTTP controllers → Blade views: returns views · Controllers render server-side pages.
- Use-case actions → Action contracts: implements · Actions fulfill contract-based use cases.
- Use-case actions → Eloquent models: persists via · Use cases operate on Eloquent entities.
- Eloquent models → Domain traits: uses · Models reuse shared traits for relationships and queries.
- Time sessions → Eloquent models: writes · Working sessions are converted into time-tracking records.
- Time sessions → Pause timing: feeds · Pause and resting-time logic depends on session state.
- Pause timing → Eloquent models: updates · Recalculation affects pause-time and tracking data.
- Absence calendar → Vacation rules: depends on · Absence calendars reflect entitlement and ban rules.
- Vacation rules → Eloquent models: stores in · Vacation data is persisted through domain models.
- Public holidays → Use-case actions: imports via · Holiday ingestion is performed through dedicated actions.
- Public holidays → Eloquent models: stores in · Imported holidays become location-scoped records.
- Reports → Eloquent models: reads · Reports aggregate time, absence, and target-hour data.
- Reports → Use-case actions: filters via · Period evaluation is driven by domain actions and filters.
- Middleware → Auth & tenancy: enforces · Middleware supports current-location and auth boundaries.
- Jobs & mail → Auth & tenancy: notifies · Operational emails are part of account and absence workflows.
- Console & queue → Pause timing: runs · Console commands execute recalculations and scheduled work.
- Build assets → Blade views: supplies assets · Blade views are styled and scripted by compiled frontend assets.