How eporsche/daybreak works
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: Models Eloquent models · Actions Use-case actions · FortifyServiceProvider.php Auth & tenancy · web.php Web routes
Components 20
Entry & UI
Browser entrypoints, routing, controllers, Livewire, and Blade views.
- Web routes · Primary browser entrypoint for the monolith.
routes/web.php - API routes · Secondary API entrypoint used sparingly.
routes/api.php - HTTP controllers · Thin request handlers for account, location, time, absence, and reports.
app/Http/Controllers - Livewire UI · Interactive server-rendered screens for core workflows.
app/Http/Livewire - Blade views · Rendered pages, layouts, and mail templates.
resources/views
Domain Core
Business actions, contracts, models, and supporting domain services.
- Use-case actions · Domain operations for creating, updating, approving, importing, and deleting.
app/Actions - Action contracts · Interfaces that define expected use-case behavior.
app/Contracts - Eloquent models · Core tenant, location, employee, time, absence, and entitlement entities.
app/Models - Domain traits · 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 · Working-session state machine and conversion into persisted tracking records.
app/StateMachine/WorkingSession - Pause timing · Pause-time calculation, resting-time rules, and recalculation command.
app/Console/Commands/RecalculatePauseTimes.php - Absence calendar · Calendar rendering and absence calculation for day-by-day planning.
app/AbsenceCalendar - Vacation rules · Entitlements, bans, transfers, and approval workflow for leave.
app/Models/VacationEntitlement.php - Public holidays · Holiday client, import action, and location-specific holiday data.
app/Holiday - Reports · Period-based evaluation and report row building.
app/Report
Platform
Auth, middleware, queue, console, and deployment/runtime support.
- Auth & tenancy · Fortify/Jetstream, policies, and current-location enforcement.
app/Providers/FortifyServiceProvider.php - Middleware · Request filters including current-location enforcement and auth/session guards.
app/Http/Middleware - Jobs & mail · Queued jobs and operational email notifications.
app/Jobs - Console & queue · Artisan kernel and command scheduling/execution.
app/Console - Build assets · Compiled frontend assets and bundling setup.
webpack.mix.js
Connections 24
- 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.