# andmari11/timeflex architecture

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

- Interactive diagram: https://gitdiagram.com/andmari11/timeflex
- Repository: https://github.com/andmari11/timeflex

## Overview

##### Project Type and Purpose
- This is a full‑stack web application built on the Laravel PHP framework, augmented by a Python FastAPI microservice for optimization routines. Its primary use case is employee scheduling, shift exchanges, statistics gathering, notifications and form handling (TimeFlex).

##### File Structure Analysis
- Top‑level Laravel monolith:
- app/Http/Controllers → HTTP controllers (MVC controllers)
- app/Models → Eloquent ORM models representing tables (User, Schedule, Shift, etc.)
- resources/views → Blade templates for the server‑rendered UI
- resources/js & resources/css → front‑end assets (bundled via Vite)
- routes/web.php & routes/console.php → HTTP and CLI routing
- config/, bootstrap/ → framework configuration and bootstrapping
- database/migrations & seeders → schema definitions and initial data
- storage/, public/ → persistent storage and web‑root
- fastApi/ → standalone Python microservice powered by FastAPI, handling optimization (shift assignments, preference solving)

##### Key README Insights
- Standard Laravel setup (composer install, .env, php artisan)
- Python service launched via Uvicorn on port 8001, invoked by the PHP app (FastAPI endpoints)

##### Diagramming the Architecture
a. Main Components
1. Client Browser (User Interface)
2. Web Server (Nginx/Apache) + Laravel PHP application
3. Database (MySQL/PostgreSQL)
4. Python FastAPI Microservice
5. Queue/Cache (Redis or DB‑backed queues)
6. Storage (local disk or S3 via Filesystems)
7. Optional Services (Email SMTP, third‑party APIs)
b. Relationships & Data Flows
- Browser → (HTTPS) → Laravel Routes → Controllers → Models → Database
- Browser → static assets served from public/ (CSS, JS)
- Laravel → (HTTP) → FastAPI service → returns JSON results → Laravel processes & stores in DB
- Laravel jobs dispatched to queue → workers consume jobs (e.g., email notifications)
- Database reads/writes by both Laravel and queue workers
c. Architectural Patterns & Principles
- MVC within the Laravel monolith
- Single‐responsibility controllers & Eloquent models
- Service boundary between PHP monolith and Python microservice
- Asynchronous processing via queues
- Separation of concerns for presentation (Blade), application logic (Controllers/Services), and data (Models/DB)
d. Key Technologies & Libraries
- PHP 8.x, Laravel framework, Eloquent ORM, Composer
- Blade templating, Vite (ESBuild), Tailwind/CSS (if used)
- FastAPI, Uvicorn, httpx for inter‑service communication
- MySQL or PostgreSQL (per .env), Redis for cache/queues (optional)
- Apache/Nginx as HTTP server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client"
        Browser["Client Browser"]:::external
        AssetsJs["resources/js/app.js"]:::asset
        AssetsCss["resources/css/app.css"]:::asset
        Vite["vite.config.js"]:::asset
        Entry["public/index.php"]:::asset
    end

    %% Laravel Monolith
    subgraph "Laravel Monolith"
        Routes["HTTP & CLI Routing"]:::php
        Controllers["Controllers (app/Http/Controllers/)"]:::php
        Models["Eloquent Models (app/Models/)"]:::php
        Views["Blade Templates (resources/views/)"]:::php
        Config["Configuration & Bootstrap (config/, bootstrap/)"]:::php
        Migrations["Migrations & Seeders (database/migrations/)"]:::php
    end

    %% Queue & Cache
    subgraph "Queue / Cache"
        Queue["Queue/Cache (Redis or DB)"]:::queue
    end

    %% Database
    DB[(Database)]:::db

    %% Storage & Public
    subgraph "Storage / Public"
        Storage["Storage & Public Assets (storage/, public/)"]:::external
    end

    %% Python Microservice
    subgraph "FastAPI Microservice" 
        fastMain["fastApi/main.py"]:::python
        fastOpt["fastApi/optimize1.py"]:::python
    end

    %% External Services
    SMTP["SMTP / Email Service"]:::external
    S3["File Storage (S3)"]:::external

    %% Connections - synchronous
    Browser -->|HTTPS| Entry
    Browser -->|GET static assets| AssetsJs
    Browser -->|GET static assets| AssetsCss
    Entry -->|routes| Routes
    Routes -->|invoke| Controllers
    Controllers -->|query/write| Models
    Controllers -->|render| Views
    Controllers -->|use config| Config
    Controllers -->|migrate/seed| Migrations
    Models -->|SQL| DB

    %% Microservice call
    Controllers -->|HTTP JSON| fastMain
    fastMain -->|calls optimize| fastOpt
    fastMain -->|return JSON| Controllers

    %% Asynchronous
    Controllers -.->|dispatch| Queue
    Queue -.->|consume jobs| Controllers

    %% Storage and external
    Controllers -->|store files| Storage
    Controllers -->|send email| SMTP
    Controllers -->|store/retrieve| S3

    %% Database from queue
    Queue -->|read/write| DB

    %% Styles and assets pipeline (example)
    AssetsJs -->|bundled by Vite| Entry
    AssetsCss -->|bundled by Vite| Entry

    %% Click Events
    click AssetsJs "https://github.com/andmari11/timeflex/blob/main/resources/js/app.js"
    click AssetsCss "https://github.com/andmari11/timeflex/blob/main/resources/css/app.css"
    click Vite "https://github.com/andmari11/timeflex/blob/main/vite.config.js"
    click Entry "https://github.com/andmari11/timeflex/blob/main/public/index.php"
    click Routes "https://github.com/andmari11/timeflex/blob/main/routes/web.php"
    click Controllers "https://github.com/andmari11/timeflex/tree/main/app/Http/Controllers/"
    click Models "https://github.com/andmari11/timeflex/tree/main/app/Models/"
    click Views "https://github.com/andmari11/timeflex/tree/main/resources/views/"
    click Config "https://github.com/andmari11/timeflex/blob/main/config/app.php"
    click Migrations "https://github.com/andmari11/timeflex/tree/main/database/migrations/"

    click fastMain "https://github.com/andmari11/timeflex/blob/main/fastApi/main.py"
    click fastOpt "https://github.com/andmari11/timeflex/blob/main/fastApi/optimize1.py"

    %% Classes
    classDef php fill:#f2d7d5,stroke:#d98880,color:#641e16
    classDef python fill:#d6eaf8,stroke:#85c1e9,color:#1b4f72
    classDef db fill:#d4efdf,stroke:#52be80,color:#145a32
    classDef queue fill:#fcf3cf,stroke:#f7dc6f,color:#7d6608
    classDef asset fill:#e8daef,stroke:#bb8fce,color:#4a235a
    classDef external fill:#ebdef0,stroke:#af7ac5,color:#4a235a
```
