# ispa-io/ispa-cms architecture

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

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

## Overview

##### Project Type & Purpose
- This is a full-stack web application and CMS boilerplate.
- The backend is built on Laravel (version 9.x) with a typical MVC pattern (controllers, models, views, middleware, etc.).
- The front end uses Vite with Vue3 (powered with TypeScript) and TailwindCss for styling.
- Docker is used for containerization, including MySQL and custom PHP configurations.
- The README outlines the roadmap for features such as Enumerate management, audit logs, users/roles/permissions, and unit testing, indicating modular and extensible design.

##### Key Components from the File Structure
A. Infrastructure/Deployment:
- .docker folder, docker-compose.yml, and related scripts – these indicate containerized services (web, PHP, MySQL, etc.).
- Environment configuration file (.env.example) plus configuration files in the config directory.

B. Backend (Laravel):
- “app” directory:
– Console commands (e.g., MakeController, MakeModel) that help in scaffolding.
– HTTP layer: Controllers (grouped under Admin, API versioning via V1), Middleware, Requests (for form validation), and Policies.
– Domain logic: Models, Repositories (both interfaces and eloquent implementation), Observers, and Event Listeners.
– Supporting directories like Constants, Helpers, Providers.
- “routes” directory with API, web, and console route definitions.
- Database migrations, seeders, factories (under “database”), which define the database schema and initial data.
- Test suite (unit tests and test helper files).

C. Frontend:
- “resources” directory with JS (Vite entry points & bootstrap) and Blade templates (views).
- Public assets in “public” (including index.php entry point for Laravel).

##### Relationships & Interactions
- The frontend (Vue3) communicates with the backend through defined API endpoints (see routes/api.php and controllers under app/Http/Controllers/V1/Admin).
- The backend applies business logic, interacts with the database (via migrations, models, and repositories), and returns JSON or rendered views.
- Middleware components handle security, authentication, and request processing.
- Events, listeners, and observers reflect key design patterns used for decoupling e.g., AuditLog events.
- Docker abstracts the infrastructure: one container handles the PHP/Laravel app while others may handle the database (MySQL) and other services.

##### Architectural Patterns & Design Principles
- MVC Pattern: Clear separation between Controllers, Models, and Views.
- Repository Pattern: Separation of data access logic (app/Repositories) from business logic.
- Service Providers and Events: Used for bootstrapping, dependency injection, and decoupled communication.
- Containerization with Docker facilitates environment consistency and deployment.
- Modular design: The structure supports features like Enumerates, Audit Logs, and Role/Permission management in a segregated manner.
- Frontend/Backend separation: Use of Vite plus Vue3 for the client-side while Laravel serves as the API and/or full-stack server.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External / User
    UB("Browser"):::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        FE1("Vue3/Vite+TailwindCss"):::frontend
        FE2("Blade Templates"):::frontend
    end

    %% Application Layer (Backend - Laravel)
    subgraph "Application Layer (Backend - Laravel)"
        BE2("Middleware"):::backend
        BE1("Controllers [Admin,API V1]"):::backend
        BE3("Requests (Validation/FormHandling)"):::backend
        BE4("Policies"):::backend
        BE5("Service Providers"):::backend
        BE6("Models"):::backend
        BE7("Repositories"):::backend
        BE8("Console Commands"):::backend
        BE9("Events/Listeners/Observers"):::backend
    end

    %% Data/Domain Layer
    subgraph "Data/Domain Layer"
        DM1("Migrations &Seeders"):::database
        DB("MySQL Database"):::database
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        IN1("Docker Configuration"):::infrastructure
        IN2("Public Assets"):::infrastructure
    end

    %% Connections for HTTP requests via Public Assets and Frontend
    UB -->|"HTTP_Request"| IN2
    IN2 -->|"Bootstrap_Laravel"| BE2
    UB -->|"SPA/API_Request"| FE1
    FE1 -->|"Calls_API"| BE1
    FE2 -->|"Renders_View"| BE1

    %% Backend internal interactions
    BE2 -->|"Forwards_Request"| BE1
    BE1 -->|"Uses_Model"| BE6
    BE1 -->|"Calls_Repo"| BE7
    BE1 -->|"Triggers_Event"| BE9
    BE5 -->|"Bootstraps"| BE1
    BE3 -->|"Validates_Input"| BE1

    %% Data Access connections
    BE6 -->|"Persists_Data"| DM1
    BE7 -->|"Fetches_Data"| DM1
    DM1 -->|"Operates_on"| DB

    %% Infrastructure links to Application and Data layers
    IN1 -->|"Hosts_App"| BE1
    IN1 -->|"Hosts_App"| BE2
    IN1 -->|"Hosts_Env"| BE5
    IN1 -->|"Provides_DB_Container"| DB

    %% Click Events for Infrastructure/Deployment
    click IN1 "https://github.com/ispa-io/ispa-cms/blob/main/.docker"
    click IN1 "https://github.com/ispa-io/ispa-cms/blob/main/docker-compose.yml"
    click IN1 "https://github.com/ispa-io/ispa-cms/blob/main/.docker/php.ini"
    click IN1 "https://github.com/ispa-io/ispa-cms/tree/main/.docker/start-container"
    click IN1 "https://github.com/ispa-io/ispa-cms/blob/main/.env.example"

    %% Click Events for Backend – Laravel Application
    click BE1 "https://github.com/ispa-io/ispa-cms/tree/main/app/Http/Controllers"
    click BE2 "https://github.com/ispa-io/ispa-cms/tree/main/app/Http/Middleware"
    click BE8 "https://github.com/ispa-io/ispa-cms/tree/main/app/Console/Commands"
    click BE8 "https://github.com/ispa-io/ispa-cms/tree/main/app/Console/Commands/stubs"
    click BE6 "https://github.com/ispa-io/ispa-cms/tree/main/app/Models"
    click BE7 "https://github.com/ispa-io/ispa-cms/tree/main/app/Repositories"
    click BE4 "https://github.com/ispa-io/ispa-cms/tree/main/app/Policies"
    click BE5 "https://github.com/ispa-io/ispa-cms/tree/main/app/Providers"
    click BE3 "https://github.com/ispa-io/ispa-cms/tree/main/app/Http/Requests"
    click BE9 "https://github.com/ispa-io/ispa-cms/tree/main/app/Events"
    click BE9 "https://github.com/ispa-io/ispa-cms/tree/main/app/Listeners"
    click BE9 "https://github.com/ispa-io/ispa-cms/tree/main/app/Observers"

    %% Click Events for Data Access / Domain
    click DM1 "https://github.com/ispa-io/ispa-cms/tree/main/database/migrations"
    click DM1 "https://github.com/ispa-io/ispa-cms/tree/main/database/seeders"

    %% Click Events for Frontend (Presentation Layer)
    click FE1 "https://github.com/ispa-io/ispa-cms/tree/main/resources/js"
    click FE1 "https://github.com/ispa-io/ispa-cms/blob/main/vite.config.js"
    click FE1 "https://github.com/ispa-io/ispa-cms/blob/main/resources/css/app.css"
    click FE2 "https://github.com/ispa-io/ispa-cms/tree/main/resources/views"

    %% Click Events for Public Assets
    click IN2 "https://github.com/ispa-io/ispa-cms/blob/main/public/index.php"

    %% Styling Classes
    class UB external
    class FE1,FE2 frontend
    class BE1,BE2,BE3,BE4,BE5,BE6,BE7,BE8,BE9 backend
    class DM1,DB database
    class IN1,IN2 infrastructure

classDef external fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
classDef backend fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
classDef database fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
classDef infrastructure fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
