# ledermann/pingcrm architecture

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

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

## Overview

##### Main Components
- Frontend Layer:
- Inertia.js – This is the glue that bridges the Rails backend and the Vue.js frontend, handling page visits without full page reloads.
- Backend Layer:
- Rails Controllers – Found in app/controllers; note special concerns (like inertia_csrf, inertia_flash, inertia_json) that indicate cross-layer data handling via Inertia.
- Models & Business Logic – Located in app/models and services in app/services. Models such as User, Account, Contact, and Organization encapsulate the business data and rules.
- Views – Although Rails uses views, here they are combined with Inertia (see app/views/layouts) primarily for layout and mailer templates.
- Database:
- PostgreSQL (specified in README). Represent it clearly as the persistent storage that interacts with Rails models (migrations and schema defined in db/).
- Supporting Components:
- Mailers (app/mailers) – Manage email notifications.
- Tests – Represented in the test/ directory for system, integration, and model tests.
- External Integrations & Dependencies – Include Docker (Dockerfile, docker-compose.yml, scripts under docker/), CI/CD workflows (GitHub Actions under .github/workflows), and configuration files (e.g., config/initializers for Inertia, Devise, etc.).

##### Relationships and Interactions
- User Browser → Frontend UI: The user interacts with Vue.js thereby triggering actions.
- Frontend UI ↔ Inertia Middleware: Inertia acts as the conduit between the client-side Vue.js components and server-side Rails controllers.
- Rails Controllers → Models: Business logic operations, data validations, and database interactions occur here.
- Rails Models ↔ Database: Use Rails migrations (in db/migrate) and schema (db/schema.rb) as a representation of the database design.
- Configuration & Services: Show how initializers and services (e.g., auth_failure in app/services) tie into both controller logic and external API integrations (if any).
- Testing & Deployment: Indicate separate flows for CI/CD (GitHub workflows) and local development (bin/dev, docker-compose) that reflect how changes propagate through testing and deployment pipelines.

##### Architectural Patterns and Design Principles
- MVC Pattern: Clearly separate the Model (app/models), View (app/views and Vue components), and Controller (app/controllers) responsibilities.
- Inertia.js Integration: Emphasize how Inertia replaces traditional API calls with a server-side rendered approach that mimics SPA behavior.
- Separation of Concerns: Distinguish between frontend elements (with Vue.js) and backend logic (Rails), including shared components like authentication (Devise, controllers/users/sessions_controller.rb) and authorization (app/models/ability.rb).

##### Putting It All Together
- At the top, place “User Browser” interacting with the “Vue.js Frontend/SPA”.
- Beneath that, illustrate the “Inertia.js Bridge” connecting the frontend and the “Rails Server”.
- Within the “Rails Server”, detail the MVC structure by partitioning it into Controllers, Models, and Views (layouts, mailers).
- Adding a side section or callouts for:
- Deployment configurations (Docker, GitHub Actions) that ensure continuous integration and smooth deployment.
- Tooling for testing (Rails System Tests, Integration Tests).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    UB("User Browser"):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        VJS("Vue.js Components"):::frontend
        INERTIA("Inertia.js Integration"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        RC("Rails Controllers"):::backend
        RM("Rails Models"):::backend
        SVC("Services"):::backend
        VIEWS("Views & Layouts"):::backend
        MAIL("Mailers"):::backend
    end

    %% Database Layer
    DB("PostgreSQL Database"):::database

    %% Supporting & Deployment
    subgraph "Supporting & Deployment"
        TEST("Testing"):::support
        DOCKER("Docker & Deployment"):::support
        CICD("CI/CD Workflows"):::support
        CONFIG("Configurations"):::support
    end

    %% Data Flow Connections
    UB -->|"interacts"| VJS
    VJS -->|"uses"| INERTIA
    INERTIA -->|"bridges to"| RC
    RC -->|"calls"| RM
    RM -->|"persists in"| DB
    RC -->|"delegates to"| SVC
    RC -->|"renders"| VIEWS
    RC -->|"sends via"| MAIL
    RC -->|"configuredBy"| CONFIG
    RC -->|"verifiedBy"| TEST
    DOCKER -->|"CI/CD"| CICD
    CONFIG -->|"deploys"| CICD

    %% Styling Classes
    classDef frontend fill:#FFEEAD,stroke:#B58900,stroke-width:2px;
    classDef backend fill:#C6E2FF,stroke:#268BD2,stroke-width:2px;
    classDef database fill:#C3F9BB,stroke:#2AA198,stroke-width:2px;
    classDef support fill:#FCE6C9,stroke:#D33682,stroke-width:2px;
    classDef external fill:#FFD1DC,stroke:#CB4B16,stroke-width:2px;

    %% Click Events
    click VJS "https://github.com/ledermann/pingcrm/tree/master/app/javascript"
    click INERTIA "https://github.com/ledermann/pingcrm/blob/master/app/javascript/entrypoints/application.js"
    click RC "https://github.com/ledermann/pingcrm/tree/master/app/controllers"
    click RM "https://github.com/ledermann/pingcrm/tree/master/app/models"
    click SVC "https://github.com/ledermann/pingcrm/tree/master/app/services"
    click VIEWS "https://github.com/ledermann/pingcrm/tree/master/app/views/layouts"
    click MAIL "https://github.com/ledermann/pingcrm/tree/master/app/mailers"
    click DB "https://github.com/ledermann/pingcrm/tree/master/db"
    click TEST "https://github.com/ledermann/pingcrm/tree/master/test"
    click DOCKER "https://github.com/ledermann/pingcrm/tree/master/docker/"
    click CICD "https://github.com/ledermann/pingcrm/tree/master/.github/workflows"
    click CONFIG "https://github.com/ledermann/pingcrm/tree/master/config/initializers"
```
