How solidtime-io/solidtime works
Project Type and Purpose
• solidtime is a full-stack, monolithic web application built on Laravel (PHP) for the backend and Vue 3 (with Inertia.js and Vite) for the frontend.
• It provides time-tracking features for freelancers/agencies: projects, tasks, clients, multi-organization, billable rates, import/export, REST API, and an admin UI (Filament).
File Structure Highlights
• app/ ··· Laravel application code (Controllers, Models, Services, Actions, Jobs, Events).
• routes/ (api.php, web.php) ··· defines public/private API endpoints (versioned) and Inertia/web routes.
• resources/js/ ··· Vue components, layouts, pages, composables, plus two packaged libraries: packages/api (TypeScript API client) & packages/ui (UI component library).
• config/, bootstrap/, storage/, database/ ··· Laravel config, bootstrapping, file storage, migrations & seeders.
• public/ ··· Nginx/Apache entrypoint (index.php), assets.
• docker/ & docker-compose.yml ··· local and production Docker setups (PHP-FPM/Octane/Queue workers, MinIO, PostgreSQL).
• .github/workflows & CI config ··· build, lint, test, publish pipelines for PHP and NPM packages.
• tests/ & e2e/ & playwright/ ··· unit tests (PHPUnit), E2E tests (Playwright).
a. Clients
• Browser (SPA via Inertia) for web UI and admin panel (Filament).
• CLI (artisan commands, importers).
• External API consumers (swagger/OpenAPI).
b. Web Server Layer
• PHP-FPM / Octane (Swoole / RoadRunner / FrankenPHP) running Laravel.
• Ingress / HTTPS termination (nginx or cloud load balancer).
c. Application Layer (Laravel)
• HTTP Controllers (Web & Api\V1) → Routes → Middleware → Controllers → Services/Actions → Models.
• Filament Admin Panel.
• Fortify & Jetstream (authentication & user management).
• Passport OAuth server (personal access tokens).
• Queues & Workers (Horizon / supervisord).
• Scheduled Jobs (cron / Octane scheduler).
d. Data Layer
• PostgreSQL (primary DB).
• Redis (cache, session, queue).
• MinIO / Filesystem (user uploads, exported reports, temp files).
e. Third-Party & External
• Email (SMTP / mail provider).
• Importer APIs (Toggl, Clockify, Harvest).
• Analytics / Telemetry endpoint (self-hosted).
f. DevOps
• Docker Compose (local development).
• GitHub Actions (CI/CD for PHP & NPM).
• Deployment scripts (docker/prod).
Component Interactions
• Browser → HTTPS → Load Balancer → PHP Server → Laravel Router
• Web routes render Vue via Inertia.
• API routes respond with JSON (used by SPA & external clients).
• Laravel Queue publishes jobs to Redis → Workers (supervisord) consume.
• Models ↔ PostgreSQL via Eloquent ORM.
• Cache & Sessions ↔ Redis.
• File storage calls MinIO or local FS.
• OAuth flows via Passport controllers.
• Importers fetch external data → transform into DTOs → persist via Services.
• Scheduled commands triggered by cron/octane scheduler.
• CI builds NPM packages (api client, UI components) → published to npmjs.org.
• E2E tests (Playwright) simulate browser interactions.
Architectural Patterns & Principles
• MVC (Models, Controllers, Views/Resources).
• Service Layer & Action classes (single-responsibility).
• DTOs for import/export and API resources.
• Event-Driven (Events & Listeners) and Job Queue.
• Modular TS packages for UI and API client.
• Layered separation: Presentation (Vue), Application (Controllers/Services), Domain (Models/Enums), Infrastructure (DB, Cache, Queues).
Technologies & Frameworks
• Backend: PHP 8.3, Laravel, Passport, Fortify, Jetstream, Filament Admin.
• Frontend: Vue 3, Inertia.js, Vite, TypeScript.
• Data: PostgreSQL, Redis, MinIO.
• DevOps: Docker, GitHub Actions, Supervisord, Octane (RoadRunner/Swoole/FrankenPHP).
• Testing: PHPUnit, Playwright (E2E).
Essential Elements
• Clear component names (e.g., “AuthenticationController”, “ReportExportService”).
• Arrowheads showing request/response or publish/subscribe (for queues).
• Notes on key middleware (ForceJsonResponse, Authenticate, etc.) at boundary of API webserver.
• Deployment targets: local Docker vs. production supervisor configs.