Atomic CRM

Atomic CRM is a full-featured, open-source CRM originally developed by Marmelab and extended here with a fully documented, repeatable deployment process.

This repository focuses on:

• deterministic local setup (WSL + Docker)
• Supabase-backed auth and data
• Vercel-based frontend deployment
• automation-ready documentation

Demo (upstream):
https://marmelab.com/atomic-crm-demo

---

🚀 Start Here (Required Reading)

If you are setting up this project locally or deploying it yourself, start with these documents in order:

1. 📘 Installation
   → docs/INSTALLATION.md
   Canonical, step-by-step setup from a fresh machine.

2. 🧠 Lessons Learned
   → docs/LESSONS_LEARNED.md
   Root causes of issues encountered during real deployments, and how they were fixed.

3. 🛠 Troubleshooting
   → docs/TROUBLESHOOTING.md
   Symptom → cause → fix reference.

4. 🧩 Architecture
   → docs/ARCHITECTURE.md
   System boundaries, environments, and trust model.

If something is not written in these docs, it is not considered part of the supported setup.

---

🔐 Environment Variables (Important)

This project does not commit environment files.

Local development

• .env.local or .env.development
• gitignored
• used by local tooling (Vite, Supabase functions, scripts)
• developer-specific values

Production

• No .env.production file is committed
• Values live in:
  • Vercel Environment Variables (Frontend)
  • Supabase Secrets (Edge Functions, if used)

The committed file .env.example defines the required schema only.

---

✨ Features

• 📇 Organize Contacts – Centralized contact management
• ⏰ Tasks & Reminders – Never miss a follow-up
• 📝 Notes – Capture insights and context
• ✉️ Inbound Email Capture – Save emails as CRM notes
• 📊 Deal Management – Kanban-style sales pipeline
• 🔄 Import / Export – Move data in and out easily
• 🔐 Authentication – Google, Azure, Keycloak, Auth0
• 📜 Activity History – Aggregated interaction logs
• 🔗 API Integration – Connect external systems
• 🛠️ Customizable – Fields, themes, components

---

📚 User Documentation (Upstream)

• User Management
• Importing and Exporting Data
• Inbound Email

---

🚢 Deploying to Production (Upstream Guides)

• Configuring Supabase
• Inbound Email Configuration (optional)
• Deployment Guide

These guides describe the application’s capabilities.
The canonical install flow for this repo lives in docs/INSTALLATION.md.

---

🎨 Customizing Atomic CRM

Customisation requires TypeScript and React knowledge.

• Customizing the CRM
• Creating Migrations
• Data Providers
• Architecture Decisions

---

🧪 Testing

Run unit tests with:

make test
Tests use Jest and live alongside source files as *.test.ts or *.test.tsx.

📦 Registry
Atomic CRM components are published as a Shadcn Registry:

registry.json is generated by scripts/generate-registry.mjs (pre-commit hook)

The published registry lives at:
http://marmelab.com/atomic-crm/r/atomic-crm.json

⚠️ If registry.json is missing changes, update scripts/generate-registry.mjs.

📄 License
MIT License, courtesy of Marmelab.
See LICENSE.md.