# solidtime-io/solidtime architecture

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

- Interactive diagram: https://gitdiagram.com/solidtime-io/solidtime
- Repository: https://github.com/solidtime-io/solidtime

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        direction TB
        Browser["Browser (SPA via Inertia)"]:::external
        CLI["CLI (Artisan, Importers)"]:::external
        ExternalAPIs["3rd-Party APIs (Toggl, Harvest, Clockify)"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        LB["Load Balancer / Nginx (HTTPS:443)"]:::infra
        PHPServer["PHP-FPM / Octane (RoadRunner/Swoole)"]:::infra
        DockerCompose["Docker Compose (Local/Prod)"]:::infra
        GitHubActions["GitHub Actions CI/CD"]:::infra
    end

    Browser -->|"HTTPS"| LB
    CLI -->|"Artisan/Queue"| PHPServer
    ExternalAPIs -->|Import calls| ImportSub

    LB -->|"HTTP"| PHPServer

    %% Frontend
    subgraph "Frontend"
        direction TB
        SPA["Vue 3 + Inertia SPA"]:::app
        APIClient["TS API Client Lib"]:::app
        UILib["TS UI Component Lib"]:::app
    end
    Browser --> SPA
    SPA -->|Ajax/API| APIClient
    SPA -->|UI comps| UILib
    APIClient -->|HTTP| LB

    %% Backend Application Layer
    subgraph "Backend Application"
        direction TB
        WebRoutes["routes/web.php"]:::app
        ApiRoutes["routes/api.php"]:::app
        MW["Middleware"]:::app
        Controllers["Web Controllers"]:::app
        APIControllers["API Controllers"]:::app
        Filament["Filament Admin Panel"]:::app
        Auth["Fortify/Jetstream/Passport"]:::app
        Services["Services & Actions"]:::app
        ImportSub["Import Subsystem"]:::app
        DTO["DTOs"]:::app
        Jobs["Jobs & Queues"]:::app
        Sched["Scheduled Commands"]:::app
        Models["Eloquent Models"]:::app
    end

    PHPServer --> WebRoutes
    PHPServer --> ApiRoutes
    WebRoutes --> MW
    ApiRoutes --> MW
    MW --> Controllers
    MW --> APIControllers
    Controllers --> Services
    APIControllers --> Services
    Controllers -->|Admin| Filament
    Services --> Models
    Models --> PostgreSQL
    Services --> Redis
    Services --> MinIO

    %% Import subsystem
    ImportSub --> DTO
    DTO --> Services
    Services --> Models

    %% Jobs & Scheduler
    Services --> Jobs
    Jobs -->|Publish to Redis| Redis
    Redis -->|Consume| PHPServer
    Sched --> Services

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PostgreSQL["PostgreSQL (DB:5432)"]:::data
        Redis["Redis (Cache/Queue:6379)"]:::data
        MinIO["MinIO / Filesystem"]:::data
    end

    %% DevOps
    GitHubActions --> DockerCompose

    %% Click Events
    click WebRoutes "https://github.com/solidtime-io/solidtime/blob/main/routes/web.php"
    click ApiRoutes "https://github.com/solidtime-io/solidtime/blob/main/routes/api.php"
    click Controllers "https://github.com/solidtime-io/solidtime/tree/main/app/Http/Controllers/Web"
    click APIControllers "https://github.com/solidtime-io/solidtime/tree/main/app/Http/Controllers/Api/V1"
    click MW "https://github.com/solidtime-io/solidtime/tree/main/app/Http/Middleware"
    click Models "https://github.com/solidtime-io/solidtime/tree/main/app/Models"
    click ImportSub "https://github.com/solidtime-io/solidtime/blob/main/app/Service/Import/ImportService.php"
    click ImportSub "https://github.com/solidtime-io/solidtime/tree/main/app/Service/Import/Importers"
    click Jobs "https://github.com/solidtime-io/solidtime/tree/main/app/Jobs"
    click Sched "https://github.com/solidtime-io/solidtime/blob/main/app/Console/Kernel.php"
    click Auth "https://github.com/solidtime-io/solidtime/blob/main/config/fortify.php"
    click Filament "https://github.com/solidtime-io/solidtime/tree/main/app/Filament/Resources"
    click APIClient "https://github.com/solidtime-io/solidtime/tree/main/resources/js/packages/api"
    click UILib "https://github.com/solidtime-io/solidtime/tree/main/resources/js/packages/ui"
    click DockerCompose "https://github.com/solidtime-io/solidtime/blob/main/docker-compose.yml"
    click GitHubActions "https://github.com/solidtime-io/solidtime/tree/main/.github/workflows"

    %% Styles
    classDef external fill:#a8f0c6,stroke:#2d7f5e,color:#000
    classDef infra fill:#d3d3d3,stroke:#777,color:#000
    classDef app fill:#cde5ff,stroke:#1e60a8,color:#000
    classDef data fill:#ffd9a8,stroke:#b8751f,color:#000
```
