# chlnlto/malvar-ems architecture

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

- Interactive diagram: https://gitdiagram.com/chlnlto/malvar-ems
- Repository: https://github.com/chlnlto/malvar-ems

## Overview

##### Project type and purpose
- This is a Laravel‐based full-stack web application with an integrated Filament admin panel. It manages municipal data such as barangays, companies, waste collection schedules, environmental clearances, announcements, documents, officials, and user records. It also provides export (XLSX/CSV) and PDF certificate generation features.

##### File structure
- Top-level directories:
- app/: application code (Models, Controllers, Policies, Services, Filament resources & widgets)
- config/: framework and package configuration
- database/: migrations and seeders
- public/: web assets (CSS/JS), index.php entry point
- resources/: Blade views, front-end CSS/JS sources
- routes/: web and console routes
- storage/: logs, caches, file uploads
- scripts/: deployment helpers
- tests/: unit and feature tests
- Key patterns:
- MVC (app/Models + app/Http/Controllers + resources/views)
- Service layer (app/Services, app/Exports)
- Filament Admin (app/Filament – Resources, Pages, Widgets)
- Authorization via Policies

##### README
- Generic Laravel framework README; confirms this is a Laravel web app but does not describe custom architecture. So rely on file structure for domain specifics.

##### Main components and their relationships
a. Frontend (Browser + Assets)
- Blade templates (resources/views)
- Filament UI (app/Filament + public/css & public/js/filament)
b. Web Server & Entry Point
- Nginx/Apache → public/index.php → Laravel HTTP kernel
c. Routing & HTTP Layer
- routes/web.php & console.php → Middleware → Controllers (e.g. HomeController, BarangayController, ExportController, PDFCertificateController)
d. Service Layer & Business Logic
- app/Services (PDFCertificateService) and app/Exports (EnvironmentalClearanceExport, etc.)
e. Domain Models & Data Access
- app/Models (Eloquent ORM)
- app/Policies (authorization)
f. Persistence & Infrastructure
- Database (MySQL/PostgreSQL) via config/database.php
- Migrations & Seeders populate tables
- Cache & Sessions (file, Redis, etc.)
- Queue (jobs table or Redis)
- Filesystem (local “storage/app/public” & “storage/app/private”)
g. External Services
- Mail (SMTP via config/mail.php)
- Broadcasting (Pusher/Echo in public/js/filament/echo.js)
- Third-party APIs (if any) configured in config/services.php
h. CI/CD & Deployment
- GitHub Actions (/.github/workflows/deploy.yml)
- Deployment scripts (scripts/deployment/*.sh)

##### Architectural patterns & design principles
- Layered architecture: Presentation → Application → Domain → Infrastructure
- MVC for the core app
- Service-oriented components for PDF generation & data export
- Policy-based authorization
- Filament as a module‐based admin panel using Livewire
- Separation of concerns: Controllers delegate to Services/Exports/Models

##### Relationships & data flow
- HTTP request from Browser → Web Server → Laravel Router
- Router → Controller → Service/Model → Database
- Service → Export/PDF generation → Storage or Response
- Response → Controller → Blade/Livewire → Browser
- Background jobs enqueued by Controllers → Queue Workers → Services → Database/Storage
- File uploads/downloads via Storage layer → public URLs

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "CI/CD & Deployment"
    GH["GitHub Repository"]:::infra
    Deploy["Deployment Scripts"]:::infra
    GH -->|"runs Actions"| Deploy
    click GH "https://github.com/chlnlto/malvar-ems/blob/main/.github/workflows/deploy.yml"
    click Deploy "https://github.com/chlnlto/malvar-ems/blob/main/scripts/deployment/prepare-for-deploy.sh"
  end

  subgraph "User Interface"
    Browser["Web Browser"]:::ui
    Views["Blade Templates (resources/views)"]:::ui
    Assets["Static Assets (public/css/filament & public/js/filament)"]:::ui
    Browser -->|"requests page"| Views
    Browser -->|"loads assets"| Assets
    click Views "https://github.com/chlnlto/malvar-ems/tree/main/resources/views"
    click Assets "https://github.com/chlnlto/malvar-ems/tree/main/public/css/filament"
    click Assets "https://github.com/chlnlto/malvar-ems/tree/main/public/js/filament"
  end

  subgraph "Application Server"
    WebServer["Web Server (Nginx/Apache)"]:::infra
    Entry["Entry Point (public/index.php)"]:::infra
    Router["Router (routes/web.php & routes/console.php)"]:::app
    Middleware["Middleware & Authorization Policies"]:::app
    Controllers["Controllers (app/Http/Controllers)"]:::app
    Services["Services & Exports"]:::app
    Models["Domain Models (app/Models)"]:::app
    Filament["Filament Admin Panel (app/Filament)"]:::app
    AdminProvider["AdminPanelProvider"]:::app
    QueueWorker["Queue Worker"]:::infra

    Browser -->|"HTTP Request"| WebServer
    WebServer --> Entry
    Entry --> Router
    Router --> Middleware
    Middleware --> Controllers
    Controllers --> Services
    Services --> Models
    Controllers --> Filament
    Filament --> AdminProvider
    Controllers --> QueueWorker
    QueueWorker --> Services

    click Entry "https://github.com/chlnlto/malvar-ems/blob/main/public/index.php"
    click Router "https://github.com/chlnlto/malvar-ems/blob/main/routes/web.php"
    click Router "https://github.com/chlnlto/malvar-ems/blob/main/routes/console.php"
    click Middleware "https://github.com/chlnlto/malvar-ems/blob/main/app/Providers/AppServiceProvider.php"
    click Controllers "https://github.com/chlnlto/malvar-ems/tree/main/app/Http/Controllers"
    click Services "https://github.com/chlnlto/malvar-ems/blob/main/app/Services/PDFCertificateService.php"
    click Services "https://github.com/chlnlto/malvar-ems/blob/main/app/Exports/EnvironmentalClearanceExport.php"
    click Services "https://github.com/chlnlto/malvar-ems/blob/main/app/Exports/GarbageCollectionScheduleExport.php"
    click Services "https://github.com/chlnlto/malvar-ems/blob/main/app/Exports/WasteCollectionReportExport.php"
    click Models "https://github.com/chlnlto/malvar-ems/tree/main/app/Models"
    click Filament "https://github.com/chlnlto/malvar-ems/tree/main/app/Filament"
    click AdminProvider "https://github.com/chlnlto/malvar-ems/blob/main/app/Providers/Filament/AdminPanelProvider.php"
  end

  subgraph "Data & Infrastructure"
    DB["Relational Database"]:::data
    Cache["Cache Store"]:::data
    Queue["Queue Backend"]:::data
    Storage["File Storage"]:::data
    Mail["Mail Service (SMTP)"]:::external
    Broadcast["Broadcasting (Pusher/Echo)"]:::external

    Services --> DB
    Services --> Storage
    Controllers --> Storage
    QueueWorker --> DB
    QueueWorker --> Storage
    Controllers --> Mail
    Controllers --> Broadcast

    click DB "https://github.com/chlnlto/malvar-ems/blob/main/config/database.php"
    click Cache "https://github.com/chlnlto/malvar-ems/blob/main/config/cache.php"
    click Queue "https://github.com/chlnlto/malvar-ems/blob/main/config/queue.php"
    click Storage "https://github.com/chlnlto/malvar-ems/tree/main/storage/app/public"
    click Mail "https://github.com/chlnlto/malvar-ems/blob/main/config/mail.php"
    click Broadcast "https://github.com/chlnlto/malvar-ems/blob/main/public/js/filament/echo.js"
  end

  classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef app fill:#90EE90,stroke:#000,stroke-width:1px
  classDef data fill:#FFA500,stroke:#000,stroke-width:1px
  classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#000,stroke-dasharray:2 2
```
