A full-featured CRM built with React, shadcn/ui, and Supabase.
Add Agents.md
fzaninottoc1943176705f
diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 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 FakeRestdiff --git a/CALUDE.md b/CALUDE.mdnew file mode 100644index 00000000..eef4bd20--- /dev/null+++ b/CALUDE.md@@ -0,0 +1 @@\ No newline at end of file