How fatfreecrm/fat_free_crm works
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)