# roskus/prospero-flow-crm architecture

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

- Interactive diagram: https://gitdiagram.com/roskus/prospero-flow-crm
- Repository: https://github.com/roskus/prospero-flow-crm

## Overview

##### Project Type & Purpose
- This is a full-stack, open-source CRM built on Laravel 11 that features multi-company support, multi-language capabilities, and a REST API for integration.
- The project follows conventional Laravel project structure using MVC (and modular separation) patterns, with clear segregation of API endpoints and web views.

##### Overall File Structure
- The "app" directory holds the core business logic: controllers (notably in app/Http/Controllers and its many sub-folders by module such as Account, Api, Bank, Brand, etc.), models (in app/Models), helpers, jobs, mail, and services.
- The "resources/views" folder contains all Blade templates for the UI, indicating a traditional presentation layer.
- The "routes" directory distinguishes API routes (api.php and module subdirectories) from web routes (web.php), which strengthens the separation between the public REST API and the user interface.
- The "database" directory (including factories, migrations, and seeders) represents the data access layer.
- The "config" directory and various infrastructure scripts (in etc/infrastructure and Docker compose files) outline deployment concerns and environment configuration.
- Additionally, the "public" directory holds assets (CSS, JS, images) and entry files (index.php) serving as the front door to the application.

##### Key Components
- Presentation Layer:
- Web Client: Represented by the browser interacting with the UI (Blade templates, CSS/JS served from the "public" folder).
- Mobile/Third-Party Client: REST API consumers.

- API / Gateway Layer:
- API Controllers: Under app/Http/Controllers/Api which deal with authentication, lead management, customer management, and more.
- API Endpoints: Clearly defined routes in routes/api.php and routes/module directories.

- Backend / Business Logic Layer:
- HTTP Controllers (non-API) handling UI interactions.
- Services and Jobs: For business logic operations like scheduled notifications (artisan console commands and jobs like MailSender).
- Repository Layer: Found in app/Repositories that abstracts data retrieval.
- Helper and Trait files that support business rules.

- Data Layer:
- Models & Migrations: In app/Models and database/migrations representing entities such as lead, customer, product, order, etc.
- External Databases: MariaDB, Postgres, or MS SQL Server as configured.
- Cache and Session Management: Utilizing Redis (configured via etc/infrastructure/redis).

- Infrastructure / Deployment:
- Docker Containers: A PHP container (with Laravel, using the Dockerfile in etc/infrastructure/php), a container for the database (docker-compose files for MariaDB, Postgres, or MS SQL), and supporting containers like Redis and Web Server (Nginx).
- Web Server: Nginx configured in etc/infrastructure/nginx serving static assets and proxying requests to the PHP container.
- External Services: JWT authentication (with certs in storage/certs), Scheduled Tasks (via cron calling php artisan schedule:run), and testing/CI pipelines integrated via GitHub workflows.

##### Relationships & Interactions
- The Web Client interacts with the Presentation Layer, which makes HTTP requests to Laravel controllers.
- API Clients directly invoke REST API endpoints defined under /api.
- Controllers communicate with the service layer to execute business logic.
- The Service/Repository Layer interacts with Models to query or update the database.
- Background Jobs (queued via Laravel) and Cron tasks (triggered via scheduling) operate asynchronously to manage mail sending, notifications, etc.

##### Architectural Patterns/Design Principles
- MVC Pattern: Clearly separating the Model, View, and Controller.
- Layered Architecture: Presentation, Business Logic, and Data Access layers.
- Modularization: Organized by domain within the controllers, routes, models, repositories, and jobs.
- REST API: Clean separation between web (Blade views) and API endpoints.

##### Elements
- Component Labels: Identify each layer (Presentation, API Gateway, Business Logic, Data Access, Infrastructure).
- Data Storage: Indicate your databases, cache systems (Redis), and any external storage.
- Integration Points: Label connections between Docker containers, external API clients, and internal messaging (e.g., using queues).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        PC("Web Client (Browser)"):::presentation
        BT("Blade Templates"):::presentation
        SA("Static Assets"):::presentation
    end

    %% API / Gateway Layer
    subgraph "API / Gateway Layer"
        API_Client("API Client (Mobile/3rd Party)"):::api
        AR("API Routes"):::api
        AC("API Controllers"):::api
    end

    %% Backend / Business Logic Layer
    subgraph "Backend / Business Logic Layer"
        HTC("HTTP Controllers"):::backend
        S("Services"):::backend
        J("Jobs"):::backend
        R("Repositories"):::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        M("Models"):::data
        MIG("Migrations"):::data
        FS("Factories/Seeders"):::data
        DB("Database (MariaDB/Postgres/MS SQL)"):::data
    end

    %% Infrastructure / Deployment
    subgraph "Infrastructure / Deployment"
        DP("Docker PHP"):::infrastructure
        NET("Nginx Web Server"):::infrastructure
        RED("Redis"):::infrastructure
        CFG("Configuration"):::infrastructure
    end

    %% Relationships and Data Flow
    PC -->|"loads"| BT
    BT -->|"initiates_call"| HTC
    PC -->|"fetches"| SA
    NET -->|"serves"| SA

    API_Client -->|"REST_call"| AR
    AR -->|"routes_to"| AC

    HTC -->|"invokes"| S
    S -->|"utilizes"| R
    R -->|"accesses"| M
    M -->|"interacts_with"| DB
    S -.->|"triggers_async"| J

    NET -->|"proxies_to"| DP
    DP -->|"executes"| HTC
    DP -->|"executes"| AC

    CFG -->|"configures"| DP
    CFG -->|"configures"| NET
    RED -->|"caches_for"| S

    %% Click Events
    click BT "https://github.com/roskus/prospero-flow-crm/tree/main/resources/views"
    click SA "https://github.com/roskus/prospero-flow-crm/tree/main/public"
    click AC "https://github.com/roskus/prospero-flow-crm/tree/main/app/Http/Controllers/Api"
    click AR "https://github.com/roskus/prospero-flow-crm/blob/main/routes/api.php"
    click HTC "https://github.com/roskus/prospero-flow-crm/tree/main/app/Http/Controllers"
    click S "https://github.com/roskus/prospero-flow-crm/tree/main/app/Services"
    click J "https://github.com/roskus/prospero-flow-crm/tree/main/app/Jobs"
    click R "https://github.com/roskus/prospero-flow-crm/tree/main/app/Repositories"
    click M "https://github.com/roskus/prospero-flow-crm/tree/main/app/Models"
    click MIG "https://github.com/roskus/prospero-flow-crm/tree/main/database/migrations"
    click FS "https://github.com/roskus/prospero-flow-crm/tree/main/database/factories"
    click DP "https://github.com/roskus/prospero-flow-crm/tree/main/etc/infrastructure/php"
    click NET "https://github.com/roskus/prospero-flow-crm/tree/main/etc/infrastructure/nginx"
    click RED "https://github.com/roskus/prospero-flow-crm/blob/main/etc/infrastructure/redis/redis.conf"
    click CFG "https://github.com/roskus/prospero-flow-crm/tree/main/config/"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef backend fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef data fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef infrastructure fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
