# armandoch85/restaurante architecture

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

- Interactive diagram: https://gitdiagram.com/armandoch85/restaurante
- Repository: https://github.com/armandoch85/restaurante

## Overview

##### Project Type & Purpose
- This is a full-stack Laravel web application serving as a Restaurant POS & Electronic Invoicing system.
- Key features include:
- Point-of-Sale UI (Livewire components under app/Livewire and resources/views/pos)
- Table-map management (Livewire / Filament pages under app/Filament and resources/views)
- Filament-powered admin panel for CRUD on orders, products, invoices, reservations, etc.
- Electronic billing integration with SUNAT (app/Services/SunatService, multiple Console commands for SUNAT operations)
- Background tasks (Console commands, scheduled jobs, events/listeners)

##### File Structure & Architectural Patterns
- Top-level directories reflect a classic Laravel MVC + layered architecture:
- app/Http/Controllers → HTTP entry points (MVC controllers for web & API)
- app/Livewire → reactive components for POS, table maps, profit projections
- app/Filament → admin panel Resources, Pages & Widgets
- app/Console/Commands → batch jobs & CLI operations (e.g., Sunat tests, data fixes)
- app/Events & app/Listeners → event-driven flows (e.g., UpdateCashRegisterTotals)
- app/Services → domain services (ReservationService, SunatService)
- app/Models → Eloquent ORM models for every business entity
- database/migrations & seeders → schema evolution and initial data
- Architectural patterns:
- MVC for HTTP requests
- Service Layer for domain logic
- Event-Listener for decoupled post-action processing
- Command Pattern for scheduled/CLI tasks
- Livewire for SPA-like interactivity without a JS framework

- Client Tier
- Browser / POS Terminal (loads public/index.php; runs Vue/Tailwind assets via Vite)
- Real-time UI via Livewire and Filament JS
- Web Server Tier
- Nginx/Apache → public/index.php → Laravel Kernel
- HTTP Controllers (app/Http/Controllers)
- Livewire Handlers (app/Livewire)
- Filament Admin Panel (app/Filament)
- Application Core
- Models (app/Models) interacting with the Database
- Services (app/Services) encapsulating business rules (e.g., SunatService, ReservationService)
- Events & Listeners for asynchronous domain reactions
- Background Processing
- Scheduler/Cron invoking artisan schedule:run → Console Commands
- Queue Worker (config/queue.php, using Redis or database) processing jobs dispatched by controllers or events
- Data & Storage
- Relational Database (MySQL/PostgreSQL) hosting all tables (users, orders, invoices, tables, products, etc.)
- File Storage (local or S3) for uploads and generated PDFs (invoice, comanda)
- Cache / Session backend (Redis or file)
- External Services
- SUNAT Electronic Invoicing API (app/Services/SunatService)
- SMTP / Mailer for notifications (config/mail.php)
- Optional WebSocket / Broadcasting (Echo, Pusher) for real-time updates

##### Relationships & Interactions
- Client → HTTP controllers → Service Layer → Eloquent → Database
- Controllers / Services dispatch Events → Listeners handle side effects (e.g., notifications, cash-register updates)
- Controllers & Events dispatch Jobs → queued into Redis / database → processed by Worker → call external APIs (SUNAT)
- Scheduler triggers Console Commands (e.g., CheckSunatConfig, GenerateTestInvoice) → reuse same Services/Events
- WebSocket broadcaster pushes real-time changes to browser (table status, new orders)

##### Architectural Patterns & Design Principles
- Single Responsibility: Controllers delegate business logic to Services
- Separation of Concerns:
- Presentation (Blade, Livewire, Filament)
- Domain Logic (Services, Models)
- Infrastructure (Database, Queue, External APIs)
- Event-Driven: decouple side-effects (Listeners for totals recalculation, notifications)
- Command Scheduler: periodic maintenance and SUNAT sync

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client UI
    subgraph "Client UI"
        Browser["Browser / POS Terminal"]:::ui
        FilamentUI["Filament Admin UI"]:::ui
    end

    %% Web Application
    subgraph "Web Application"
        Controllers["HTTP Controllers"]:::core
        subgraph "POS UI"
            POSComp["PointOfSale Livewire"]:::ui
            POSView["POS Blade View"]:::ui
        end
        subgraph "TableMap UI"
            EnhancedTableMap["EnhancedTableMap"]:::ui
            QrTableMap["QrTableMap"]:::ui
            TableMapView["TableMapView"]:::ui
        end
        FilamentPanel["Filament Admin Panel"]:::core
        Services["Services (Domain)"]:::core
        Events["Events & Listeners"]:::core
        Models["Eloquent Models"]:::core
    end

    %% Background Services
    subgraph "Background Services"
        Scheduler["Scheduler & Cron"]:::bg
        QueueWorker["Queue Worker"]:::bg
        ConsoleCmds["Console Commands"]:::bg
    end

    %% Data Layer
    subgraph "Data & Storage"
        DB["Database"]:::db
        Cache["Cache / Session"]:::db
        FileStorage["File Storage"]:::storage
    end

    %% External APIs
    subgraph "External APIs"
        Sunat["SUNAT API"]:::ext
        SMTP["SMTP / Mailer"]:::ext
        Broadcast["WebSocket / Broadcasting"]:::ext
    end

    %% Relationships
    Browser -->|"HTTPS"| Controllers
    Browser -->|"Livewire/Filament"| POSComp
    FilamentUI -->|"HTTPS"| Controllers
    Controllers -->|calls| Services
    Services -->|uses| Models
    Models -->|"SQL"| DB
    Controllers -->|dispatches| Events
    Events -->|push jobs| QueueWorker
    Controllers -->|dispatch jobs| QueueWorker
    QueueWorker -->|calls| Sunat
    Controllers -->|stores files| FileStorage
    Controllers -->|sends emails| SMTP
    Models -->|caches| Cache
    Scheduler -->|runs| ConsoleCmds
    ConsoleCmds -->|uses| Services
    ConsoleCmds -->|dispatches| Events

    %% Click Events
    click Controllers "https://github.com/armandoch85/restaurante/tree/main/app/Http/Controllers/"
    click POSComp "https://github.com/armandoch85/restaurante/blob/main/app/Livewire/Pos/PointOfSale.php"
    click POSView "https://github.com/armandoch85/restaurante/blob/main/resources/views/livewire/pos/point-of-sale.blade.php"
    click EnhancedTableMap "https://github.com/armandoch85/restaurante/blob/main/app/Livewire/TableMap/EnhancedTableMap.php"
    click QrTableMap "https://github.com/armandoch85/restaurante/blob/main/app/Livewire/TableMap/QrTableMap.php"
    click TableMapView "https://github.com/armandoch85/restaurante/blob/main/app/Livewire/TableMap/TableMapView.php"
    click FilamentUI "https://github.com/armandoch85/restaurante/tree/main/app/Filament/Pages/"
    click FilamentPanel "https://github.com/armandoch85/restaurante/tree/main/app/Filament/Resources/"
    click Services "https://github.com/armandoch85/restaurante/blob/main/app/Services/SunatService.php"
    click ConsoleCmds "https://github.com/armandoch85/restaurante/tree/main/app/Console/Commands/"
    click Scheduler "https://github.com/armandoch85/restaurante/blob/main/routes/console.php"
    click Events "https://github.com/armandoch85/restaurante/tree/main/app/Events/"
    click Listeners "https://github.com/armandoch85/restaurante/tree/main/app/Listeners/"
    click Models "https://github.com/armandoch85/restaurante/tree/main/app/Models/"
    click DB "https://github.com/armandoch85/restaurante/tree/main/database/migrations/"
    click Cache "https://github.com/armandoch85/restaurante/blob/main/config/queue.php"
    click FileStorage "https://github.com/armandoch85/restaurante/blob/main/config/filesystems.php"
    click SMTP "https://github.com/armandoch85/restaurante/blob/main/config/mail.php"

    %% Styles
    classDef ui fill:#CCE5FF,stroke:#004085
    classDef core fill:#D4EDDA,stroke:#155724
    classDef bg fill:#FFF3CD,stroke:#856404
    classDef db fill:#E2E3E5,stroke:#6C757D
    classDef storage fill:#E2E3E5,stroke:#6C757D
    classDef ext fill:#E2D6F3,stroke:#4B0082
```
