# liorocks/pingcrm-react architecture

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

- Interactive diagram: https://gitdiagram.com/liorocks/pingcrm-react
- Repository: https://github.com/liorocks/pingcrm-react

## Overview

##### Project Type and Purpose
- This is a full-stack demo CRM application (“Ping CRM React”) showcasing how Laravel (PHP) and React integrate via Inertia.js.
- The Laravel backend exposes controllers, models and routes (MVC), while the React front-end renders pages and components. Inertia.js glues them together, providing SPA behavior without a separate API.

##### File Structure Analysis
- Top-level folders:
- app/ (Laravel MVC code: Controllers, Middleware, Models, Requests, Resources)
- resources/js/ (React components, layouts, pages, utilities, TypeScript types)
- database/ (migrations, factories, seeders)
- config/ (Laravel config)
- public/ (entry point index.php, compiled assets, robots.txt)
- routes/ (web.php, console.php)
- tests/ (PHPUnit feature tests)
- root config files (composer.json, package.json, vite.config.js, tailwind.config.js, .env.example)
- Build scripts / dev tooling: Vite (vite.config.js), Tailwind CSS, NPM scripts, Composer, Makefile, Procfile (for Heroku).

##### Key README Insights
- Purpose: illustrate Inertia.js bridging Laravel and React.
- Tech stack: Laravel, Inertia.js, React, Vite, Tailwind.
- Database: SQLite by default (can be swapped), seeded with users, organizations, contacts.

a. Main Components
- Browser / Client: React SPA entry (public/index.php loads Laravel, serves initial HTML, then React hydration via Inertia).
- Inertia.js Middleware: intercepts requests, serializes props, returns Inertia responses (JSON + page component name).
- HTTP Layer & Routing: routes/web.php defines endpoints; HTTP Kernel loads middleware (TrustProxies, HandleInertiaRequests, Sanctum for auth).
- Controllers (app/Http/Controllers): handle requests (Auth\LoginController, ContactsController, UsersController, etc.), invoke Request validation, interact with Models, return Inertia::render or Resource JSON.
- Models & ORM: Eloquent models (User, Organization, Contact, Account) handle database interactions.
- Database: SQLite/MySQL/Postgres; schema managed via migrations; seeded data via seeders and factories.
- Asset Pipeline: Vite compiles resources/js and resources/css into public/build; served by Laravel’s mix middleware.
- External Services: Mail (config/mail.php), optional file storage (public uploads), third-party APIs (config/services.php).
- Testing: PHPUnit tests exercising feature flows via HTTP requests.

b. Relationships & Data Flow
1. User interacts with React UI (components/pages under resources/js/Pages).
2. Inertia intercepts link/navigation/forms → axios/fetch calls to Laravel endpoints.
3. Laravel routing → middleware → controller.
4. Controller validates Request → uses Eloquent Model → reads/writes DB.
5. Controller returns an Inertia response: page component + props (data) → sent as JSON.
6. Inertia on the client side updates the React component tree with new props.
7. Assets (JS/CSS) served from public/build; environment variables loaded from .env.
8. Tests simulate HTTP requests at the routing layer, assert JSON or HTTP response.

c. Architectural Patterns & Principles
- MVC on the backend (Controllers, Models, Views abstracted as Inertia pages)
- Component-based UI on the frontend (React + TSX)
- Single-page application via Inertia.js (no separate REST API)
- RESTful resource controllers (~ContactsController, UsersController, OrganizationsController)
- Layered architecture: Presentation (React/Inertia), Application (Laravel controllers/services), Data (Eloquent/DB).
- Use of middleware pipeline for cross-cutting concerns (auth, CSRF, proxies).

d. Key Technologies
- Backend: Laravel, PHP 7+, Composer packages, Sanctum for SPA auth.
- Frontend: React, TypeScript, Inertia.js, Vite, Tailwind CSS, Axios.
- Database: SQLite/MySQL/Postgres, Eloquent ORM, migrations & seeders.
- Testing: PHPUnit, Laravel’s testing helpers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser/Client"]:::frontend
        InertiaClient["Inertia.js (Client)"]:::frontend
        subgraph "resources/js (React SPA)"
            direction TB
            App["app.tsx"]:::frontend
            Layout["MainLayout.tsx"]:::frontend
            Pages["Pages (Auth, Dashboard, Contacts, Orgs, Users, Reports, Error)"]:::frontend
            Components["Components (Alert, Button, Table, etc.)"]:::frontend
            Types["Types & Utils"]:::frontend
        end
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        Kernel["HTTP Kernel"]:::middleware
        subgraph "Middleware"
            direction TB
            TrustProxies["TrustProxies.php"]:::middleware
            InertiaMiddleware["HandleInertiaRequests.php"]:::middleware
            Sanctum["Sanctum Middleware"]:::middleware
        end
        Routes["web.php (Routing)"]:::middleware
        subgraph "Controllers"
            direction TB
            LoginCtrl["Auth/LoginController.php"]:::controller
            DashboardCtrl["DashboardController.php"]:::controller
            ContactsCtrl["ContactsController.php"]:::controller
            OrgsCtrl["OrganizationsController.php"]:::controller
            UsersCtrl["UsersController.php"]:::controller
            ReportsCtrl["ReportsController.php"]:::controller
            ImagesCtrl["ImagesController.php"]:::controller
        end
        subgraph "Requests & Resources"
            direction TB
            Requests["Request Validation (Login, ContactStore/Update, OrgStore/Update, UserStore/Update/Delete)"]:::controller
            Resources["API Resources (Contact, Org, User, Collections)"]:::controller
        end
        subgraph "Models"
            direction TB
            UserModel["User.php"]:::model
            OrgModel["Organization.php"]:::model
            ContactModel["Contact.php"]:::model
            AccountModel["Account.php"]:::model
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["Database (SQLite/MySQL/Postgres)"]:::db
        subgraph "Migrations & Seeding"
            direction TB
            Migrations["database/migrations"]:::db
            Factories["database/factories"]:::db
            Seeders["DatabaseSeeder.php"]:::db
        end
        Storage["File Storage"]:::db
    end

    %% Asset Pipeline
    subgraph "Asset Pipeline & Build Tools"
        direction TB
        Vite["vite.config.js"]:::tool
        Tailwind["tailwind.config.js"]:::tool
        CSS["resources/css"]:::tool
    end

    %% Connections
    Browser -->|interacts with| InertiaClient
    InertiaClient -->|requests via axios/fetch| Routes
    Routes -->|handles via| Kernel
    Kernel -->|runs| TrustProxies
    Kernel -->|runs| InertiaMiddleware
    Kernel -->|runs| Sanctum
    Routes -->|dispatches to| LoginCtrl
    Routes -->|dispatches to| DashboardCtrl
    Routes -->|dispatches to| ContactsCtrl
    Routes -->|dispatches to| OrgsCtrl
    Routes -->|dispatches to| UsersCtrl
    Routes -->|dispatches to| ReportsCtrl
    Routes -->|dispatches to| ImagesCtrl
    Controllers -->|validate with| Requests
    Controllers -->|serialize with| Resources
    Controllers -->|use| Models
    Models -->|query| DB
    DB -->|schema from| Migrations
    DB -->|seed data| Seeders
    Seeders -->|use| Factories
    Browser -->|loads assets| CSS
    CSS -->|built by| Tailwind
    App -->|import| Layout
    App -->|load pages/components| Pages
    Pages -->|use| Components
    App -->|use types/util| Types
    CSS -->|built by| Vite
    App -->|built by| Vite

    %% Click Events
    click InertiaMiddleware "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Middleware/HandleInertiaRequests.php"
    click TrustProxies "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Middleware/TrustProxies.php"
    click Routes "https://github.com/liorocks/pingcrm-react/blob/main/routes/web.php"
    click LoginCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/Auth/LoginController.php"
    click DashboardCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/DashboardController.php"
    click ContactsCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/ContactsController.php"
    click OrgsCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/OrganizationsController.php"
    click UsersCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/UsersController.php"
    click ReportsCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/ReportsController.php"
    click ImagesCtrl "https://github.com/liorocks/pingcrm-react/blob/main/app/Http/Controllers/ImagesController.php"
    click Migrations "https://github.com/liorocks/pingcrm-react/tree/main/database/migrations"
    click Factories "https://github.com/liorocks/pingcrm-react/tree/main/database/factories"
    click Seeders "https://github.com/liorocks/pingcrm-react/blob/main/database/seeders/DatabaseSeeder.php"
    click UserModel "https://github.com/liorocks/pingcrm-react/blob/main/app/Models/User.php"
    click OrgModel "https://github.com/liorocks/pingcrm-react/blob/main/app/Models/Organization.php"
    click ContactModel "https://github.com/liorocks/pingcrm-react/blob/main/app/Models/Contact.php"
    click AccountModel "https://github.com/liorocks/pingcrm-react/blob/main/app/Models/Account.php"
    click App "https://github.com/liorocks/pingcrm-react/blob/main/resources/js/app.tsx"
    click Layout "https://github.com/liorocks/pingcrm-react/blob/main/resources/js/Layouts/MainLayout.tsx"
    click Pages "https://github.com/liorocks/pingcrm-react/tree/main/resources/js/Pages"
    click Components "https://github.com/liorocks/pingcrm-react/tree/main/resources/js/Components"
    click Types "https://github.com/liorocks/pingcrm-react/blob/main/resources/js/utils.ts"
    click Vite "https://github.com/liorocks/pingcrm-react/blob/main/vite.config.js"
    click Tailwind "https://github.com/liorocks/pingcrm-react/blob/main/tailwind.config.js"
    click CSS "https://github.com/liorocks/pingcrm-react/blob/main/resources/css/app.css"

    %% Styles
    classDef frontend fill:#E8F1FA,stroke:#3B82F6,color:#1E3A8A,stroke-width:1px;
    classDef middleware fill:#FEF3C7,stroke:#F59E0B,color:#92400E,stroke-width:1px;
    classDef controller fill:#F3E8FF,stroke:#A78BFA,color:#5B21B6,stroke-width:1px;
    classDef model fill:#DCFCE7,stroke:#22C55E,color:#166534,stroke-width:1px;
    classDef db fill:#FEE2E2,stroke:#EF4444,color:#7F1D1D,stroke-width:1px;
    classDef tool fill:#E0F2FE,stroke:#0EA5E9,color:#075985,stroke-width:1px;
```
