How roskus/prospero-flow-crm works
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).