# jmldigital/crmbuff architecture

> Architecture diagram of the GitHub repository jmldigital/crmbuff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jmldigital/crmbuff
- Repository: https://github.com/jmldigital/crmbuff

## Overview

Crmbuff is a multi-tenant, configurable CRM: users register and work with their organization’s custom object types, fields, records, and status pipelines. Managers browse filtered, paginated records and track events; admins configure object types and teams, and can transfer records. The graph follows the sampled records and events query/mutation paths. The README documents tenant isolation, duplicate-phone checks, cloning and cascade deletion, and an email-lead foundation; unsampled implementations are represented cautiously. Supabase is the persistence/auth boundary; database enforcement details were not sampled.

Main entry points: [`platform/src/features/records/services/records.service.ts`](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/services/records.service.ts) (Record data service), [`platform/src/features/records/components/RecordTable.tsx`](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/components/RecordTable.tsx) (Record table and pipeline), [`platform/src/app/app/[objectType]/page.tsx`](https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/%5BobjectType%5D/page.tsx) (Record pages), [`platform/src/features/records/components/RecordForm.tsx`](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/components/RecordForm.tsx) (Record forms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and tenancy"]
  node_marketing["Marketing and signup<br/>[page.tsx]"]
  node_auth["Authentication<br/>[server.ts]"]
  node_tenantguard["Tenant access<br/>[middleware.ts]"]
end

subgraph group_workspace["CRM workspace"]
  node_appshell["App shell<br/>[AppShell.tsx]"]
  node_onboarding["Organization onboarding<br/>[page.tsx]"]
  node_recordroutes["Record pages<br/>[page.tsx]"]
  node_recordtable["Record table and pipeline<br/>[RecordTable.tsx]"]
  node_recordform["Record forms<br/>[RecordForm.tsx]"]
  node_eventsui["Event timeline<br/>[EventTimeline.tsx]"]
end

subgraph group_admin["Administration"]
  node_objecttypes["Object types and fields"]
  node_teamadmin["Team administration<br/>[page.tsx]"]
end

subgraph group_data["Data services"]
  node_schema["Dynamic schema builder<br/>[schema-builder.ts]"]
  node_recordqueries["Record query hooks<br/>[use-records.ts]"]
  node_recordmutations["Record mutation hooks"]
  node_recordservice["Record data service<br/>[records.service.ts]"]
  node_eventhooks["Event hooks<br/>[use-events.ts]"]
  node_eventservice["Event service<br/>[events.service.ts]"]
  node_supabase["Supabase client<br/>[browser.ts]"]
  node_database[("Supabase Postgres")]
  node_emailleads["Email lead foundation<br/>[database.types.ts]"]
end

node_user(("CRM user"))

node_user -->|"visits or registers"| node_marketing
node_marketing -.->|"submits signup"| node_auth
node_user -->|"opens workspace"| node_appshell
node_appshell -.->|"passes access check"| node_tenantguard
node_user -.->|"sets up organization"| node_onboarding
node_user -->|"configures types"| node_objecttypes
node_user -->|"manages team"| node_teamadmin
node_user -->|"opens records"| node_recordroutes
node_recordroutes -.->|"renders table"| node_recordtable
node_recordroutes -->|"renders form"| node_recordform
node_recordform -->|"builds validation"| node_schema
node_recordtable -->|"queries page"| node_recordqueries
node_recordtable -->|"mutates records"| node_recordmutations
node_recordform -.->|"saves record"| node_recordmutations
node_recordqueries -->|"fetches data"| node_recordservice
node_recordmutations -->|"calls mutations"| node_recordservice
node_recordtable -->|"loads event counts"| node_recordservice
node_recordservice -->|"queries records"| node_supabase
node_eventsui -->|"uses event hooks"| node_eventhooks
node_eventhooks -->|"calls event operations"| node_eventservice
node_eventservice -->|"queries events"| node_supabase
node_supabase -->|"reads and writes"| node_database
node_recordservice -->|"invokes CRM RPCs"| node_database
node_emailleads -.->|"documents lead schema"| node_database

click node_marketing "https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/(marketing)/page.tsx"
click node_auth "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/auth/server.ts"
click node_tenantguard "https://github.com/jmldigital/crmbuff/blob/master/platform/src/middleware.ts"
click node_appshell "https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/AppShell.tsx"
click node_onboarding "https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/onboarding/page.tsx"
click node_objecttypes "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/object-types/components/ObjectTypesList.tsx"
click node_teamadmin "https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/admin/team/page.tsx"
click node_recordroutes "https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/%5BobjectType%5D/page.tsx"
click node_recordtable "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/components/RecordTable.tsx"
click node_recordform "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/components/RecordForm.tsx"
click node_schema "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/services/schema-builder.ts"
click node_recordqueries "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/hooks/use-records.ts"
click node_recordmutations "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/hooks/use-record-mutations.ts"
click node_recordservice "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/services/records.service.ts"
click node_eventsui "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/events/components/EventTimeline.tsx"
click node_eventhooks "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/events/hooks/use-events.ts"
click node_eventservice "https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/events/services/events.service.ts"
click node_supabase "https://github.com/jmldigital/crmbuff/blob/master/platform/src/lib/supabase/browser.ts"
click node_emailleads "https://github.com/jmldigital/crmbuff/blob/master/platform/src/lib/supabase/database.types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_marketing,node_auth,node_tenantguard,node_user toneBlue
class node_appshell,node_onboarding,node_recordroutes,node_recordtable,node_recordform,node_eventsui toneAmber
class node_objecttypes,node_teamadmin toneMint
class node_schema,node_recordqueries,node_recordmutations,node_recordservice,node_eventhooks,node_eventservice,node_supabase,node_database,node_emailleads toneRose
```

## Components

### Access and tenancy

- [Marketing and signup](https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/(marketing)/page.tsx): `platform/src/app/(marketing)/page.tsx`
- [Authentication](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/auth/server.ts): `platform/src/features/auth/server.ts`
- [Tenant access](https://github.com/jmldigital/crmbuff/blob/master/platform/src/middleware.ts): `platform/src/middleware.ts`

### CRM workspace

- [App shell](https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/AppShell.tsx): `platform/src/app/app/AppShell.tsx`
- [Organization onboarding](https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/onboarding/page.tsx): `platform/src/app/app/onboarding/page.tsx`
- [Record pages](https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/app/%5BobjectType%5D/page.tsx): `platform/src/app/app/[objectType]/page.tsx`
- [Record table and pipeline](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/components/RecordTable.tsx): `platform/src/features/records/components/RecordTable.tsx`
- [Record forms](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/components/RecordForm.tsx): `platform/src/features/records/components/RecordForm.tsx`
- [Event timeline](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/events/components/EventTimeline.tsx): `platform/src/features/events/components/EventTimeline.tsx`

### Administration

- [Object types and fields](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/object-types/components/ObjectTypesList.tsx): `platform/src/features/object-types/components/ObjectTypesList.tsx`
- [Team administration](https://github.com/jmldigital/crmbuff/blob/master/platform/src/app/admin/team/page.tsx): `platform/src/app/admin/team/page.tsx`

### Data services

- [Dynamic schema builder](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/services/schema-builder.ts): `platform/src/features/records/services/schema-builder.ts`
- [Record query hooks](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/hooks/use-records.ts): `platform/src/features/records/hooks/use-records.ts`
- [Record mutation hooks](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/hooks/use-record-mutations.ts): `platform/src/features/records/hooks/use-record-mutations.ts`
- [Record data service](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/records/services/records.service.ts): `platform/src/features/records/services/records.service.ts`
- [Event hooks](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/events/hooks/use-events.ts): `platform/src/features/events/hooks/use-events.ts`
- [Event service](https://github.com/jmldigital/crmbuff/blob/master/platform/src/features/events/services/events.service.ts): `platform/src/features/events/services/events.service.ts`
- [Supabase client](https://github.com/jmldigital/crmbuff/blob/master/platform/src/lib/supabase/browser.ts): `platform/src/lib/supabase/browser.ts`
- **Supabase Postgres**
- [Email lead foundation](https://github.com/jmldigital/crmbuff/blob/master/platform/src/lib/supabase/database.types.ts): `platform/src/lib/supabase/database.types.ts`

### Other components

- **CRM user**

## Connections

- CRM user → Marketing and signup: visits or registers
- Marketing and signup → Authentication: submits signup
- CRM user → App shell: opens workspace (evidence: `platform/src/app/app/AppShell.tsx`)
- App shell → Tenant access: passes access check
- CRM user → Organization onboarding: sets up organization
- CRM user → Object types and fields: configures types
- CRM user → Team administration: manages team (evidence: `platform/src/app/admin/team/page.tsx`)
- CRM user → Record pages: opens records (evidence: `platform/src/app/app/[objectType]/page.tsx`)
- Record pages → Record table and pipeline: renders table
- Record pages → Record forms: renders form
- Record forms → Dynamic schema builder: builds validation (evidence: `platform/src/features/records/components/RecordForm.tsx`)
- Record table and pipeline → Record query hooks: queries page (evidence: `platform/src/features/records/components/RecordTable.tsx`)
- Record table and pipeline → Record mutation hooks: mutates records (evidence: `platform/src/features/records/components/RecordTable.tsx`)
- Record forms → Record mutation hooks: saves record
- Record query hooks → Record data service: fetches data (evidence: `platform/src/features/records/hooks/use-records.ts`)
- Record mutation hooks → Record data service: calls mutations (evidence: `platform/src/features/records/hooks/use-record-mutations.ts`)
- Record table and pipeline → Record data service: loads event counts (evidence: `platform/src/features/records/components/RecordTable.tsx`)
- Record data service → Supabase client: queries records (evidence: `platform/src/features/records/services/records.service.ts`)
- Event timeline → Event hooks: uses event hooks (evidence: `platform/src/features/events/components/EventTimeline.tsx`)
- Event hooks → Event service: calls event operations (evidence: `platform/src/features/events/hooks/use-events.ts`)
- Event service → Supabase client: queries events (evidence: `platform/src/features/events/services/events.service.ts`)
- Supabase client → Supabase Postgres: reads and writes
- Record data service → Supabase Postgres: invokes CRM RPCs (evidence: `platform/src/features/records/services/records.service.ts`)
- Email lead foundation → Supabase Postgres: documents lead schema
