Tech Stack
Backend — server/
| Concern | Choice | Why |
|---|---|---|
| Language / Framework | PHP 8.2 + Laravel 12 | Mature ecosystem, Eloquent, queues, the team already ships Laravel. |
| API style | REST + JSON | Broadest client support; easy to mock in tests. |
| Auth | Laravel Sanctum | Simple token-based, works for SPAs and mobile. |
| RBAC | spatie/laravel-permission | Battle-tested, integrates cleanly with policies. |
| Admin panel | Filament v3 | SystemAdmin back-office with zero hand-rolled CRUD. |
| Queues | Laravel Horizon + Redis | Visible queue health, priorities, retries. |
| Testing | Pest | Expressive, fast, pairs well with Laravel. |
| Code style | Pint | Defaults match Laravel. |
| Migrations | Laravel native | Straightforward, versioned. |
| API docs | OpenAPI 3 (generated from attributes) | Feeds typed clients on web and mobile. |
Web UI — ui/
| Concern | Choice | Why |
|---|---|---|
| Bundler | Vite | Instant HMR, native ESM. |
| Framework | React 18 + TypeScript | Team familiarity, large ecosystem. |
| Routing | React Router v6 | Standard. |
| Data fetching | TanStack Query v5 | Cache + mutations; pairs perfectly with REST. |
| Client state | Zustand | Tiny, hook-native, avoids Redux boilerplate. |
| Styling | Tailwind CSS + shadcn/ui | Consistent design, copy-paste components. |
| Forms | React Hook Form + Zod | Typed, perf-friendly. |
| Tables | TanStack Table | Roster grid, attendance listings. |
| i18n | i18next | Future locales. |
| Tests | Vitest + React Testing Library + Playwright (e2e) | Fast unit + flake-resistant e2e. |
Mobile App — app/
| Concern | Choice | Why |
|---|---|---|
| Framework | Flutter (latest stable) | Single codebase, native performance, strong geo / device APIs. |
| State | Riverpod v2 | Compile-safe DI + state. |
| Routing | go_router | Declarative routes, deep links. |
| HTTP | Dio + retrofit | Typed clients, interceptors. |
| Storage | flutter_secure_storage + Hive | Secure tokens; encrypted offline punch buffer. |
| Geo | geolocator + geofence_service | Lat/lon + background geofences. |
| Device | device_info_plus + platform_device_id | Stable fingerprint. |
| Push | firebase_messaging | Android + iOS. |
| Tests | flutter_test + integration_test | Standard. |
Observability
- Logs — Monolog (Laravel) +
loki-docker-driver, shipped as JSON. - Metrics — Laravel Pulse + Prometheus exporter.
- Traces — OpenTelemetry (post-MVP).
- Uptime — Better Stack / UptimeRobot on
/upendpoint.
Infrastructure
- Docker 24, Docker Compose v2.
- Traefik v3 for TLS + routing.
- MySQL 8 with daily logical backups.
- S3-compatible object storage for exports and uploads.
- GitHub Actions for CI (lint, typecheck, Pest, Vitest, Flutter test).