# outperosys/outpero-crm architecture

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

- Interactive diagram: https://gitdiagram.com/outperosys/outpero-crm
- Repository: https://github.com/outperosys/outpero-crm

## Overview

1. This is a monolithic Next.js App Router CRM application. The UI, server-side data access, mutations, and a small set of API endpoints all live in one repo rather than being split into separate frontend/backend services.

2. The application is organized around two route groups: an auth area under `app/(auth)` and the main CRM workspace under `app/(crm)`. The CRM group contains the product’s major screens: dashboard, leads, pipeline, activity, meetings, follow-ups, tasks, services, settings, and financial documents.

3. Authentication appears to be built around Supabase, with both client and server helpers in `lib/supabase/*`, plus `lib/auth.ts` and `proxy.ts` likely enforcing session-based route protection and redirecting unauthenticated users to `/login`.

4. The main data layer uses Prisma. `prisma/schema.prisma`, the migration history, `lib/prisma.ts`, and `prisma/seed.ts` indicate a relational database-backed domain model with seeded reference data and incremental schema evolution for leads, activities, tasks, follow-ups, proposals, meetings/transcripts, invoices, receipts, services, tags, and settings.

5. User actions are concentrated in the `actions/` folder. These server actions are the primary mutation boundary for the app: they handle CRUD and workflow operations for leads, activities, notes, tasks, meetings, follow-ups, invoices, receipts, proposals, proposal templates, services, tags, settings, dashboard data, auth, and AI-assisted features.

6. The frontend is split into route-level pages and reusable feature components. Pages in `app/(crm)/*` assemble feature-specific components from `components/*`, with many client-side interactive pieces for dialogs, tables, boards, forms, and quick actions. `components/ui/*` is the shared design-system layer.

7. The lead domain is the central business object. Lead detail screens pull together related subdomains: activities, notes, tasks, meetings, follow-ups, proposals, and financial documents. This suggests the architecture is lead-centric, with other modules attached to a lead as contextual records rather than isolated workflows.

8. Dashboard and pipeline are analytics-heavy read surfaces. `lib/dashboard/*` contains scoring and insight logic, while dashboard components show pipeline snapshots, hot leads, financial overview, team snapshot, and AI insights. These screens are derived views over the core CRM data rather than separate datasets.

9. Financial documents are treated as first-class generated artifacts. Invoices and receipts have dedicated create/view/update screens, plus API routes under `app/api/financial/.../pdf` that generate downloadable PDFs. Supporting code in `lib/pdf/*` and `lib/invoice/utils.ts` indicates document rendering is handled server-side from structured business data.

10. AI is an explicit subsystem, not just an incidental helper. `lib/ai/*` contains OpenAI wiring, prompts, context builders, and placeholder handling; feature components such as follow-up generators, proposal generators, and meeting transcript tools indicate AI is used for drafting, summarization, and document assistance.

11. Proposals and proposal templates form a separate document-authoring workflow. Template management, section editing, and the proposal workspace imply a structured content model for reusable sales/proposal content, with `lib/proposal/*` and `lib/pdf/proposal-document.tsx` supporting rendering and export.

12. The app has a strong validation boundary. `lib/validations/*` centralizes schema checks for each domain entity, which likely protects server actions and keeps form inputs, mutations, and database writes consistent across the feature set.

13. Overall data flow is: authenticated user enters the Next.js app, server-rendered pages fetch domain data through Prisma-backed helpers/actions, interactive client components submit mutations through server actions, and a few specialized API routes generate PDFs or other exportable outputs. The important architectural boundaries are auth/session handling, domain actions, database persistence, AI services, and PDF/document generation.

Main entry points: [`app/(crm)/layout.tsx`](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/layout.tsx) (CRM layout), [`actions`](https://github.com/outperosys/outpero-crm/tree/master/actions) (Server actions), [`app/(crm)/leads/[id]/page.tsx`](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/leads/[id]/page.tsx) (Lead detail), [`app/(crm)/dashboard/page.tsx`](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/dashboard/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_auth["Auth"]
  node_auth_page["Login<br/>auth page<br/>[page.tsx]"]
  node_auth_helpers["Session auth<br/>auth helpers<br/>[auth.ts]"]
  node_supabase_layer["Supabase<br/>auth provider"]
end

subgraph group_group_crm["CRM workspace"]
  node_app_root["App shell<br/>Next.js root<br/>[layout.tsx]"]
  node_crm_layout["CRM layout<br/>workspace shell<br/>[layout.tsx]"]
  node_dashboard_page["Dashboard<br/>CRM screen<br/>[page.tsx]"]
  node_leads_page["Leads<br/>CRM screen<br/>[page.tsx]"]
  node_lead_detail["Lead detail<br/>CRM screen<br/>[page.tsx]"]
  node_pipeline_page["Pipeline<br/>CRM screen<br/>[page.tsx]"]
  node_activity_page["Activity<br/>CRM screen<br/>[page.tsx]"]
  node_meetings_page["Meetings<br/>CRM screen<br/>[page.tsx]"]
  node_followups_page["Follow-ups<br/>CRM screen<br/>[page.tsx]"]
  node_tasks_page["Tasks<br/>CRM screen<br/>[page.tsx]"]
  node_services_page["Services<br/>CRM screen<br/>[page.tsx]"]
  node_settings_page["Settings<br/>CRM screen<br/>[page.tsx]"]
  node_financial_page["Financial<br/>CRM screen<br/>[page.tsx]"]
end

subgraph group_group_core["Core services"]
  node_actions_bundle["Server actions<br/>mutation layer"]
  node_validations["Validation<br/>schema guards"]
  node_dashboard_logic["Dashboard logic<br/>analytics"]
  node_ai_stack["AI services<br/>AI subsystem"]
end

subgraph group_group_data["Data layer"]
  node_prisma_layer[("Prisma DB<br/>database client<br/>[prisma.ts]")]
  node_schema["Schema<br/>[schema.prisma]"]
  node_seed["Seed data<br/>db seed<br/>[seed.ts]"]
end

subgraph group_group_render["Documents"]
  node_proposal_stack["Proposal tools<br/>document workflow"]
  node_pdf_stack["PDF output<br/>document rendering"]
  node_invoice_api["Invoice PDF API<br/>api route<br/>[route.ts]"]
  node_receipt_api["Receipt PDF API<br/>api route<br/>[route.ts]"]
end

node_app_root -->|"public auth"| node_auth_page
node_app_root -->|"workspace shell"| node_crm_layout
node_auth_helpers -->|"sessions"| node_supabase_layer
node_crm_layout -->|"protects"| node_auth_helpers
node_crm_layout -->|"entry"| node_dashboard_page
node_crm_layout -->|"routes"| node_leads_page
node_crm_layout -->|"routes"| node_lead_detail
node_crm_layout -->|"routes"| node_pipeline_page
node_crm_layout -->|"routes"| node_activity_page
node_crm_layout -->|"routes"| node_meetings_page
node_crm_layout -->|"routes"| node_followups_page
node_crm_layout -->|"routes"| node_tasks_page
node_crm_layout -->|"routes"| node_services_page
node_crm_layout -->|"routes"| node_settings_page
node_crm_layout -->|"routes"| node_financial_page
node_dashboard_page -->|"reads"| node_dashboard_logic
node_dashboard_page -->|"fetches"| node_actions_bundle
node_leads_page -->|"crud"| node_actions_bundle
node_lead_detail -->|"workflows"| node_actions_bundle
node_pipeline_page -->|"updates"| node_actions_bundle
node_activity_page -->|"records"| node_actions_bundle
node_meetings_page -->|"manages"| node_actions_bundle
node_followups_page -->|"manages"| node_actions_bundle
node_tasks_page -->|"crud"| node_actions_bundle
node_services_page -->|"crud"| node_actions_bundle
node_settings_page -->|"updates"| node_actions_bundle
node_financial_page -->|"bills"| node_actions_bundle
node_actions_bundle -->|"checks"| node_validations
node_actions_bundle -->|"writes"| node_prisma_layer
node_prisma_layer -->|"models"| node_schema
node_schema -.->|"bootstraps"| node_seed
node_lead_detail -->|"proposals"| node_proposal_stack
node_lead_detail -->|"exports"| node_pdf_stack
node_financial_page -->|"downloads"| node_invoice_api
node_financial_page -->|"downloads"| node_receipt_api
node_actions_bundle -->|"assists"| node_ai_stack
node_lead_detail -.->|"drafts"| node_ai_stack
node_dashboard_page -->|"aggregates"| node_prisma_layer
node_proposal_stack -->|"renders"| node_pdf_stack

click node_app_root "https://github.com/outperosys/outpero-crm/blob/master/app/layout.tsx"
click node_auth_page "https://github.com/outperosys/outpero-crm/blob/master/app/(auth)/login/page.tsx"
click node_crm_layout "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/layout.tsx"
click node_dashboard_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/dashboard/page.tsx"
click node_leads_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/leads/page.tsx"
click node_lead_detail "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/leads/[id]/page.tsx"
click node_pipeline_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/pipeline/page.tsx"
click node_activity_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/activity/page.tsx"
click node_meetings_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/meetings/page.tsx"
click node_followups_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/follow-ups/page.tsx"
click node_tasks_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/tasks/page.tsx"
click node_services_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/services/page.tsx"
click node_settings_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/settings/page.tsx"
click node_financial_page "https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/financial/page.tsx"
click node_actions_bundle "https://github.com/outperosys/outpero-crm/tree/master/actions"
click node_auth_helpers "https://github.com/outperosys/outpero-crm/blob/master/lib/auth.ts"
click node_supabase_layer "https://github.com/outperosys/outpero-crm/tree/master/lib/supabase"
click node_prisma_layer "https://github.com/outperosys/outpero-crm/blob/master/lib/prisma.ts"
click node_schema "https://github.com/outperosys/outpero-crm/blob/master/prisma/schema.prisma"
click node_seed "https://github.com/outperosys/outpero-crm/blob/master/prisma/seed.ts"
click node_validations "https://github.com/outperosys/outpero-crm/tree/master/lib/validations"
click node_dashboard_logic "https://github.com/outperosys/outpero-crm/tree/master/lib/dashboard"
click node_ai_stack "https://github.com/outperosys/outpero-crm/tree/master/lib/ai"
click node_proposal_stack "https://github.com/outperosys/outpero-crm/tree/master/lib/proposal"
click node_pdf_stack "https://github.com/outperosys/outpero-crm/tree/master/lib/pdf"
click node_invoice_api "https://github.com/outperosys/outpero-crm/blob/master/app/api/financial/invoices/[id]/pdf/route.ts"
click node_receipt_api "https://github.com/outperosys/outpero-crm/blob/master/app/api/financial/receipts/[id]/pdf/route.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_auth_page,node_auth_helpers,node_supabase_layer toneBlue
class node_app_root,node_crm_layout,node_dashboard_page,node_leads_page,node_lead_detail,node_pipeline_page,node_activity_page,node_meetings_page,node_followups_page,node_tasks_page,node_services_page,node_settings_page,node_financial_page toneAmber
class node_actions_bundle,node_validations,node_dashboard_logic,node_ai_stack toneMint
class node_prisma_layer,node_schema,node_seed toneRose
class node_proposal_stack,node_pdf_stack,node_invoice_api,node_receipt_api toneIndigo
```

## Components

### Auth

Login and session protection

- [Login](https://github.com/outperosys/outpero-crm/blob/master/app/(auth)/login/page.tsx): auth page · Public sign-in screen · `app/(auth)/login/page.tsx`
- [Session auth](https://github.com/outperosys/outpero-crm/blob/master/lib/auth.ts): auth helpers · Supabase client/server helpers and route protection · `lib/auth.ts`
- [Supabase](https://github.com/outperosys/outpero-crm/tree/master/lib/supabase): auth provider · Client and server session integration · `lib/supabase`

### CRM workspace

Main authenticated product routes

- [App shell](https://github.com/outperosys/outpero-crm/blob/master/app/layout.tsx): Next.js root · Global app entry and shared layout · `app/layout.tsx`
- [CRM layout](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/layout.tsx): workspace shell · Authenticated shell for the CRM area · `app/(crm)/layout.tsx`
- [Dashboard](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/dashboard/page.tsx): CRM screen · Analytics and operational overview · `app/(crm)/dashboard/page.tsx`
- [Leads](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/leads/page.tsx): CRM screen · Lead list and management · `app/(crm)/leads/page.tsx`
- [Lead detail](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/leads/[id]/page.tsx): CRM screen · Lead-centric workspace with related records · `app/(crm)/leads/[id]/page.tsx`
- [Pipeline](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/pipeline/page.tsx): CRM screen · Board view for lead flow · `app/(crm)/pipeline/page.tsx`
- [Activity](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/activity/page.tsx): CRM screen · Recent CRM activity feed · `app/(crm)/activity/page.tsx`
- [Meetings](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/meetings/page.tsx): CRM screen · Meeting schedule and transcripts · `app/(crm)/meetings/page.tsx`
- [Follow-ups](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/follow-ups/page.tsx): CRM screen · Follow-up queue and completion workflow · `app/(crm)/follow-ups/page.tsx`
- [Tasks](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/tasks/page.tsx): CRM screen · Task management surface · `app/(crm)/tasks/page.tsx`
- [Services](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/services/page.tsx): CRM screen · Service catalog management · `app/(crm)/services/page.tsx`
- [Settings](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/settings/page.tsx): CRM screen · Workspace configuration form · `app/(crm)/settings/page.tsx`
- [Financial](https://github.com/outperosys/outpero-crm/blob/master/app/(crm)/financial/page.tsx): CRM screen · Invoices and receipts area · `app/(crm)/financial/page.tsx`

### Core services

Shared server-side business logic

- [Server actions](https://github.com/outperosys/outpero-crm/tree/master/actions): mutation layer · CRUD and workflow mutations for CRM domains · `actions`
- [Validation](https://github.com/outperosys/outpero-crm/tree/master/lib/validations): schema guards · Domain input validation boundary · `lib/validations`
- [Dashboard logic](https://github.com/outperosys/outpero-crm/tree/master/lib/dashboard): analytics · Scoring and insight derivation · `lib/dashboard`
- [AI services](https://github.com/outperosys/outpero-crm/tree/master/lib/ai): AI subsystem · OpenAI prompts, context, and generation helpers · `lib/ai`

### Data layer

Database schema and persistence

- [Prisma DB](https://github.com/outperosys/outpero-crm/blob/master/lib/prisma.ts): database client · Primary relational persistence layer · `lib/prisma.ts`
- [Schema](https://github.com/outperosys/outpero-crm/blob/master/prisma/schema.prisma): prisma schema · Domain model and migrations · `prisma/schema.prisma`
- [Seed data](https://github.com/outperosys/outpero-crm/blob/master/prisma/seed.ts): db seed · Reference and bootstrap data · `prisma/seed.ts`

### Documents

PDF and proposal rendering

- [Proposal tools](https://github.com/outperosys/outpero-crm/tree/master/lib/proposal): document workflow · Proposal templates, renderer, and workspace support · `lib/proposal`
- [PDF output](https://github.com/outperosys/outpero-crm/tree/master/lib/pdf): document rendering · Server-side PDF generation for financial and proposal docs · `lib/pdf`
- [Invoice PDF API](https://github.com/outperosys/outpero-crm/blob/master/app/api/financial/invoices/[id]/pdf/route.ts): api route · Download endpoint for invoice PDFs · `app/api/financial/invoices/[id]/pdf/route.ts`
- [Receipt PDF API](https://github.com/outperosys/outpero-crm/blob/master/app/api/financial/receipts/[id]/pdf/route.ts): api route · Download endpoint for receipt PDFs · `app/api/financial/receipts/[id]/pdf/route.ts`

## Connections

- App shell → Login: public auth · Routes unauthenticated users to login
- App shell → CRM layout: workspace shell · Hosts authenticated CRM routes
- Session auth → Supabase: sessions · Wraps Supabase for client and server auth
- CRM layout → Session auth: protects · Requires a valid session before entering the workspace
- CRM layout → Dashboard: entry · Loads dashboard as a primary authenticated screen
- CRM layout → Leads: routes · Provides navigation to the lead list
- CRM layout → Lead detail: routes · Provides navigation to lead detail views
- CRM layout → Pipeline: routes · Provides navigation to the pipeline board
- CRM layout → Activity: routes · Provides navigation to the activity feed
- CRM layout → Meetings: routes · Provides navigation to meetings
- CRM layout → Follow-ups: routes · Provides navigation to follow-up workflows
- CRM layout → Tasks: routes · Provides navigation to tasks
- CRM layout → Services: routes · Provides navigation to service catalog management
- CRM layout → Settings: routes · Provides navigation to workspace settings
- CRM layout → Financial: routes · Provides navigation to financial records
- Dashboard → Dashboard logic: reads · Derives scores, snapshots, and insights
- Dashboard → Server actions: fetches · Uses server actions for dashboard data
- Leads → Server actions: crud · List and mutate leads through server actions
- Lead detail → Server actions: workflows · Coordinates lead-related records and mutations
- Pipeline → Server actions: updates · Moves leads through pipeline stages
- Activity → Server actions: records · Reads and logs activities
- Meetings → Server actions: manages · Schedules and updates meetings and transcripts
- Follow-ups → Server actions: manages · Creates, completes, and drafts follow-ups
- Tasks → Server actions: crud · Task creation and status updates
- Services → Server actions: crud · Maintains the service catalog
- Settings → Server actions: updates · Saves workspace settings
- Financial → Server actions: bills · Creates and updates invoices and receipts
- Server actions → Validation: checks · Validates domain inputs before persistence
- Server actions → Prisma DB: writes · Persists CRM data through Prisma
- Prisma DB → Schema: models · Implements the schema-defined domain model
- Schema → Seed data: bootstraps · Seed script initializes reference data
- Lead detail → Proposal tools: proposals · Shows and edits proposal workflows from lead context
- Lead detail → PDF output: exports · Supports document rendering for financial/proposal artifacts
- Financial → Invoice PDF API: downloads · Invoice PDF export endpoint
- Financial → Receipt PDF API: downloads · Receipt PDF export endpoint
- Server actions → AI services: assists · Uses AI for drafting, summarization, and context-aware generation
- Lead detail → AI services: drafts · AI helpers support notes, follow-ups, and related workflows
- Dashboard → Prisma DB: aggregates · Reads core CRM data for analytics surfaces
- Proposal tools → PDF output: renders · Proposal workspace feeds PDF document generation