# fatfreecrm/fat_free_crm architecture

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

- Interactive diagram: https://gitdiagram.com/fatfreecrm/fat_free_crm
- Repository: https://github.com/fatfreecrm/fat_free_crm

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source Ruby on Rails customer relationship management (CRM) platform called Fat Free CRM.
- The project is structured as a Rails application (with an engine mode for embedding into other apps), providing web UI, RESTful controllers, ActiveRecord models, views (Haml), background processing (mail processor), and plugin extensibility.

##### File Structure Highlights
- app/ (MVC layers):
- controllers/ – HTTP endpoints, business logic
- models/ – domain entities (contacts, leads, accounts, tasks, custom fields)
- views/ – Haml templates, JS responses, XLS builders
- assets/ – JS (CoffeeScript), CSS/SCSS, images
- mailers/ – Devise, Dropbox, subscription, user notifications
- lib/fat_free_crm/ – core engine code, extensions, callbacks, plugins, mail processors
- config/ – Rails config, routes, database yml, cable (ActionCable), initializers
- db/ – migrations, seeds, demo data
- Dockerfile, .devcontainer/, docker-compose.yml, Vagrantfile – environment setup
- spec/ – full RSpec test suite
- Gemfile – dependencies (Rails, Devise, SimpleForm, etc.)

##### Key Architectural Concepts
- MVC pattern: clear separation between Models, Views, Controllers
- Rails Engine architecture: core CRM shipped as mountable engine
- Plugin/Extension points via engine and mail_processor
- Background mail processing and webhooks (Dropbox, inbound email replies)
- Optional real-time updates via ActionCable (config/cable.yml)
- File attachments via ActiveStorage (config/storage.yml, migrations)
- Deployable via Docker + Nginx + Puma or Heroku, with Procfile

##### Main Components
- User’s Browser (UI)
- Web Server Layer
- Nginx (reverse proxy)
- Puma application server
- Rails Application
- Controllers
- Views/Assets pipeline
- Models (ActiveRecord)
- Engines & Plugins (lib/fat_free_crm)
- Mail Processor
- ActionCable for real-time features
- Data Stores
- Primary relational database (MySQL / PostgreSQL / SQLite)
- ActiveStorage service (local / cloud)
- External Services
- SMTP provider (for Devise, mailers)
- Dropbox webhook endpoint
- Redis or queue backend (if used for jobs / ActionCable)
- Development / Deployment Tools
- Docker / Docker-Compose
- Vagrant (legacy)
- GitHub Actions (CI: CodeQL, RuboCop, Brakeman)

##### Relationships & Interactions
- Browser → Nginx → Puma → Rails controllers → Models → DB
- Rails → ActiveStorage for file uploads → Storage backend
- Rails → Mailers → SMTP
- Mail processor (background) polls/inbound email → Rails → database
- Rails → ActionCable → Browser for live updates
- Plugin engine hooks into controllers/models for custom fields, research tools
- CI/CD workflows trigger automated tests and security scans on commit

##### Architectural Patterns & Design Principles
- MVC core pattern for web interactions
- Engine-based modularity for core + plugins
- Observer pattern in app/models/observers for async model callbacks
- Decorator/Extension pattern in lib/fat_free_crm to open-class Rails components
- RESTful design for resources (accounts, contacts, leads, etc.)
- Convention over Configuration via Rails

##### Essential Elements
- Clear, descriptive component names
- Annotations for important modules (mail_processor, custom_fields, research_tools)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        Browser["User's Browser"]:::ui
        ViewsAssets["Views & Asset Pipeline"]:::ui
    end

    %% Web Server Layer
    subgraph "Web Server Layer"
        Nginx["Nginx"]:::app
        Puma["Puma"]:::app
    end

    %% Application Layer
    subgraph "Application Layer"
        Controllers["Rails Controllers"]:::app
        Models["Rails Models"]:::app
        Engine["Rails Engine & Plugins Core"]:::app
        Extensions["Plugin/Extension Points & Tasks"]:::app
        MailProcessor["Mail Processor"]:::app
        Mailers["Mailers"]:::app
        ActionCable["ActionCable (Real-time)"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["Primary Database"]:::data
        Storage["ActiveStorage Service"]:::data
    end

    %% External Services
    subgraph "External Services"
        SMTP["SMTP Provider"]:::ext
        DropboxWebhook["Dropbox Webhook Endpoint"]:::ext
        Redis["Redis/Queue Backend"]:::ext
    end

    %% Dev & Deployment Tools
    subgraph "Dev & Deployment Tools"
        Docker["Docker Setup"]:::tools
        Vagrant["Vagrant"]:::tools
        CICD["CI/CD Workflows"]:::tools
    end

    %% Connections
    Browser -->|"HTTP"| Nginx
    Nginx -->|"Proxy"| Puma
    Puma -->|"calls"| Controllers
    Controllers -->|"SQL"| Models
    Models -->|"read/write"| DB
    Controllers -->|"renders"| ViewsAssets
    Controllers -->|"JSON/JS"| ViewsAssets
    Controllers -->|"uploads"| Storage
    Storage -->|"stores files"| Storage
    Controllers -->|"SMTP"| SMTP
    Controllers -->|"webhook"| DropboxWebhook
    MailProcessor -.->|"polls inbound email"| Controllers
    MailProcessor -.->|"updates DB"| Models
    Controllers -->|"invokes"| Mailers
    DropboxWebhook -->|"triggers"| Mailers
    Controllers -->|"broadcast"| ActionCable
    ActionCable -.->|"WebSocket"| Browser
    Engine -.-> Controllers
    Engine -.-> Models
    Extensions -.-> Controllers
    Extensions -.-> Models
    Docker --> Puma
    Vagrant --> Puma
    CICD --> Controllers

    %% Click Events
    click Browser "https://github.com/fatfreecrm/fat_free_crm/tree/master/app/views/ and app/assets/javascripts/ and app/assets/stylesheets/"
    click Nginx "https://github.com/fatfreecrm/fat_free_crm/blob/master/.docker/nginx/sites-enabled/ffcrm.conf"
    click Puma "https://github.com/fatfreecrm/fat_free_crm/blob/master/config/puma.rb"
    click Controllers "https://github.com/fatfreecrm/fat_free_crm/blob/master/app/controllers/entities/accounts_controller.rb"
    click Models "https://github.com/fatfreecrm/fat_free_crm/blob/master/app/models/entities/contact.rb"
    click ViewsAssets "https://github.com/fatfreecrm/fat_free_crm/tree/master/app/views/leads/"
    click ViewsAssets "https://github.com/fatfreecrm/fat_free_crm/tree/master/app/assets/javascripts/"
    click ViewsAssets "https://github.com/fatfreecrm/fat_free_crm/tree/master/app/assets/stylesheets/"
    click Engine "https://github.com/fatfreecrm/fat_free_crm/blob/master/lib/fat_free_crm/engine.rb"
    click Extensions "https://github.com/fatfreecrm/fat_free_crm/blob/master/lib/tasks/ffcrm/demo.rake"
    click MailProcessor "https://github.com/fatfreecrm/fat_free_crm/blob/master/lib/fat_free_crm/mail_processor/base.rb"
    click Mailers "https://github.com/fatfreecrm/fat_free_crm/blob/master/app/mailers/user_mailer.rb"
    click ActionCable "https://github.com/fatfreecrm/fat_free_crm/blob/master/config/cable.yml"
    click DB "https://github.com/fatfreecrm/fat_free_crm/blob/master/config/database.yml"
    click DB "https://github.com/fatfreecrm/fat_free_crm/tree/master/db/migrate/"
    click Storage "https://github.com/fatfreecrm/fat_free_crm/blob/master/config/storage.yml"
    click SMTP "https://github.com/fatfreecrm/fat_free_crm/blob/master/config/initializers/action_mailer.rb"
    click DropboxWebhook "https://github.com/fatfreecrm/fat_free_crm/blob/master/app/controllers/emails_controller.rb"
    click Docker "https://github.com/fatfreecrm/fat_free_crm/tree/master/Dockerfile"
    click Docker "https://github.com/fatfreecrm/fat_free_crm/blob/master/docker-compose.yml"
    click Vagrant "https://github.com/fatfreecrm/fat_free_crm/tree/master/Vagrantfile"
    click CICD "https://github.com/fatfreecrm/fat_free_crm/blob/master/.github/workflows/codeql.yml"

    %% Styles
    classDef ui fill:#a0d8f1,stroke:#555,stroke-width:1px;
    classDef app fill:#6b8dd6,stroke:#333,stroke-width:1px;
    classDef data fill:#334d8a,stroke:#222,stroke-width:1px;
    classDef ext fill:#8a2be2,stroke:#444,stroke-width:1px;
    classDef tools fill:#888888,stroke:#000,stroke-width:1px;
```
