Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

Add Agents.md

fzaninottoc1943176705f
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..680f07c4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,187 @@
+# AGENTS.md
+
+## Project Overview
+
+Atomic CRM is a full-featured CRM built with React, shadcn-admin-kit, and Supabase. It provides contact management, task tracking, notes, email capture, and deal management with a Kanban board.
+
+## Development Commands
+
+### Setup
+```bash
+make install # Install dependencies (frontend, backend, local Supabase)
+make start # Start full stack with real API (Supabase + Vite dev server)
+make stop # Stop the stack
+make start-demo # Start full-stack with FakeRest data provider
+```
+
+### Testing and Code Quality
+
+```bash
+make test # Run unit tests (vitest)
+make typecheck # Run TypeScript type checking
+make lint # Run ESLint and Prettier checks
+```
+
+### Building
+
+```bash
+make build # Build production bundle (runs tsc + vite build)
+```
+
+### Database Management
+
+```bash
+npx supabase migration new <name> # Create new migration
+npx supabase migration up # Apply migrations locally
+npx supabase db push # Push migrations to remote
+npx supabase db reset # Reset local database (destructive)
+```
+
+### Registry (Shadcn Components)
+
+```bash
+make registry-gen # Generate registry.json (runs automatically on pre-commit)
+make registry-build # Build Shadcn registry
+```
+
+## Architecture
+
+### Technology Stack
+
+- **Frontend**: React 19 + TypeScript + Vite
+- **Routing**: React Router v7
+- **Data Fetching**: React Query (TanStack Query)
+- **Forms**: React Hook Form
+- **Application Logic**: shadcn-admin-kit + ra-core (react-admin headless)
+- **UI Components**: Shadcn UI + Radix UI
+- **Styling**: Tailwind CSS v4
+- **Backend**: Supabase (PostgreSQL + REST API + Auth + Storage + Edge Functions)
+- **Testing**: Vitest
+
+### Directory Structure
+
+```
+src/
+├── components/
+│ ├── admin/ # Shadcn Admin Kit components (mutable dependency)
+│ ├── atomic-crm/ # Main CRM application code (~15,000 LOC)
+│ │ ├── activity/ # Activity logs
+│ │ ├── companies/ # Company management
+│ │ ├── contacts/ # Contact management (includes CSV import/export)
+│ │ ├── dashboard/ # Dashboard widgets
+│ │ ├── deals/ # Deal pipeline (Kanban)
+│ │ ├── filters/ # List filters
+│ │ ├── layout/ # App layout components
+│ │ ├── login/ # Authentication pages
+│ │ ├── misc/ # Shared utilities
+│ │ ├── notes/ # Note management
+│ │ ├── providers/ # Data providers (Supabase + FakeRest)
+│ │ ├── root/ # Root CRM component
+│ │ ├── sales/ # Sales team management
+│ │ ├── settings/ # Settings page
+│ │ ├── simple-list/ # List components
+│ │ ├── tags/ # Tag management
+│ │ └── tasks/ # Task management
+│ ├── supabase/ # Supabase-specific auth components
+│ └── ui/ # Shadcn UI components (mutable dependency)
+├── hooks/ # Custom React hooks
+├── lib/ # Utility functions
+└── App.tsx # Application entry point
+
+supabase/
+├── functions/ # Edge functions (user management, inbound email)
+└── migrations/ # Database migrations
+```
+
+### Key Architecture Patterns
+
+For more details, check out the doc/src/content/docs/developers/architecture-choices.mdx document.
+
+#### Mutable Dependencies
+
+The codebase includes mutable dependencies that should be modified directly if needed:
+- `src/components/admin/`: Shadcn Admin Kit framework code
+- `src/components/ui/`: Shadcn UI components
+
+#### Configuration via `<CRM>` Component
+
+The `src/App.tsx` file renders the `<CRM>` component, which accepts props for domain-specific configuration:
+- `contactGender`: Gender options
+- `companySectors`: Company industry sectors
+- `dealCategories`, `dealStages`, `dealPipelineStatuses`: Deal configuration
+- `noteStatuses`: Note status options with colors
+- `taskTypes`: Task type options
+- `logo`, `title`: Branding
+- `lightTheme`, `darkTheme`: Theme customization
+- `disableTelemetry`: Opt-out of anonymous usage tracking
+
+#### Database Views
+
+Complex queries are handled via database views to simplify frontend code and reduce HTTP overhead. For example, `contacts_summary` provides aggregated contact data including task counts.
+
+#### Database Triggers
+
+User data syncs between Supabase's `auth.users` table and the CRM's `sales` table via triggers (see `supabase/migrations/20240730075425_init_triggers.sql`).
+
+#### Edge Functions
+
+Located in `supabase/functions/`:
+- User management (creating/updating users, account disabling)
+- Inbound email webhook processing
+
+#### Data Providers
+
+Two data providers are available:
+1. **Supabase** (default): Production backend using PostgreSQL
+2. **FakeRest**: In-browser fake API for development/demos, resets on page reload
+
+When using FakeRest, database views are emulated in the frontend. Test data generators are in `src/components/atomic-crm/providers/fakerest/dataGenerator/`.
+
+#### Filter Syntax
+
+List filters follow the `ra-data-postgrest` convention with operator concatenation: `field_name@operator` (e.g., `first_name@eq`). The FakeRest adapter maps these to FakeRest syntax at runtime.
+
+## Development Workflows
+
+### Path Aliases
+
+The project uses TypeScript path aliases configured in `tsconfig.json` and `components.json`:
+- `@/components` → `src/components`
+- `@/lib` → `src/lib`
+- `@/hooks` → `src/hooks`
+- `@/components/ui` → `src/components/ui`
+
+### Adding Custom Fields
+
+When modifying contact or company data structures:
+1. Create a migration: `npx supabase migration new <name>`
+2. Update the sample CSV: `src/components/atomic-crm/contacts/contacts_export.csv`
+3. Update the import function: `src/components/atomic-crm/contacts/useContactImport.tsx`
+4. If using FakeRest, update data generators in `src/components/atomic-crm/providers/fakerest/dataGenerator/`
+5. Don't forget to update the views
+6. Don't forget the export functions
+7. Don't forget the contact merge logic
+
+### Running with Test Data
+
+Import `test-data/contacts.csv` via the Contacts page → Import button.
+
+### Git Hooks
+
+- Pre-commit: Automatically runs `make registry-gen` to update `registry.json`
+
+### Accessing Local Services During Development
+
+- Frontend: http://localhost:5173/
+- Supabase Dashboard: http://localhost:54323/
+- REST API: http://127.0.0.1:54321
+- Storage (attachments): http://localhost:54323/project/default/storage/buckets/attachments
+- Inbucket (email testing): http://localhost:54324/
+
+## Important Notes
+
+- The codebase is intentionally small (~15,000 LOC in `src/components/atomic-crm`) for easy customization
+- Modify files in `src/components/admin` and `src/components/ui` directly - they are meant to be customized
+- Unit tests can be added in the `src/` directory (test files are named `*.test.ts` or `*.test.tsx`)
+- User deletion is not supported to avoid data loss; use account disabling instead
+- Filter operators must be supported by the `supabaseAdapter` when using FakeRest
diff --git a/CALUDE.md b/CALUDE.md
new file mode 100644
index 00000000..eef4bd20
--- /dev/null
+++ b/CALUDE.md
@@ -0,0 +1 @@
\ No newline at end of file