Project Structure

The kit follows Next.js App Router conventions with a clean separation between frontend components, backend logic, and database infrastructure.

Top-Level Structure

crm-fullstack/
├── app/                    # Next.js routes
├── components/             # React components (3-tier hierarchy)
├── data/                   # Static data (navigation, onboarding)
├── hooks/                  # Custom React hooks
├── lib/                    # Utilities, Supabase clients, Server Actions
├── supabase/               # Database migrations and seed data
├── types/                  # TypeScript type definitions
├── public/                 # Static assets
├── middleware.ts           # Auth middleware for route protection
└── .env.example            # Environment variable template

Route Groups

The app/ directory uses Next.js route groups for layout separation:

app/
├── (auth)/                 # Authentication pages
│   ├── login/
│   ├── register/
│   ├── forgot-password/
│   └── auth/               # OAuth callback and email confirm routes
│       ├── callback/
│       └── confirm/
├── (dashboard)/            # Main CRM application (protected)
│   ├── page.tsx            # Sales dashboard
│   ├── contacts/           # Contact management
│   │   ├── page.tsx        # Contact list with search and filters
│   │   ├── [id]/           # Contact detail
│   │   ├── new/            # Create contact
│   │   ├── [id]/edit/      # Edit contact
│   │   └── import/         # CSV import wizard
│   ├── companies/          # Company management
│   │   ├── page.tsx        # Company list
│   │   ├── [id]/           # Company detail
│   │   ├── new/            # Create company
│   │   └── [id]/edit/      # Edit company
│   ├── deals/              # Deal and pipeline management
│   │   ├── page.tsx        # Kanban pipeline board
│   │   ├── [id]/           # Deal detail
│   │   ├── new/            # Create deal
│   │   ├── [id]/edit/      # Edit deal
│   │   ├── settings/       # Pipeline configuration
│   │   └── forecast/       # Revenue forecasting
│   ├── tasks/              # Task management
│   │   ├── page.tsx        # Task list
│   │   ├── calendar/       # Calendar view
│   │   ├── activity/       # Activity log
│   │   └── templates/      # Email templates
│   ├── email/              # Email module
│   │   ├── page.tsx        # Email inbox
│   │   ├── compose/        # Compose email
│   │   └── sequences/      # Email sequences
│   ├── reports/            # Analytics and reporting
│   │   ├── page.tsx        # Sales overview
│   │   ├── pipeline/       # Pipeline analytics
│   │   ├── team/           # Team performance
│   │   └── revenue/        # Revenue breakdown
│   ├── settings/           # CRM settings
│   │   ├── page.tsx        # General settings
│   │   ├── team/           # Team management
│   │   ├── integrations/   # Integration settings
│   │   └── billing/        # Billing page
│   ├── notifications/      # Notification center
│   └── onboarding/         # Setup wizard
└── not-found.tsx           # 404 page

Component Hierarchy

Components follow a 3-tier system:

components/
├── ui/                     # Tier 1: shadcn/ui primitives (never modified)
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   ├── table.tsx
│   └── ...
├── contacts/               # Tier 2: Contact composites
│   ├── contacts-table.tsx
│   ├── contact-card.tsx
│   ├── contact-hero.tsx
│   ├── contact-form.tsx
│   ├── contact-filters.tsx
│   └── ...
├── companies/              # Tier 2: Company composites
│   ├── companies-table.tsx
│   ├── company-hero.tsx
│   ├── company-form.tsx
│   └── ...
├── deals/                  # Tier 2: Deal and pipeline composites
│   ├── kanban-board.tsx
│   ├── kanban-column.tsx
│   ├── kanban-card.tsx
│   ├── deal-form.tsx
│   ├── deal-hero.tsx
│   ├── pipeline-settings.tsx
│   └── ...
├── tasks/                  # Tier 2: Task composites
│   ├── task-list.tsx
│   ├── calendar-grid.tsx
│   ├── activity-log.tsx
│   └── ...
├── email/                  # Tier 2: Email composites
│   ├── email-inbox.tsx
│   ├── email-compose.tsx
│   ├── template-editor.tsx
│   ├── sequence-builder.tsx
│   └── ...
├── charts/                 # Tier 2: Chart composites
│   ├── revenue-trend-chart.tsx
│   ├── conversion-funnel.tsx
│   ├── deals-by-stage-chart.tsx
│   └── ...
├── dashboard/              # Tier 2: Dashboard composites
│   ├── stat-card.tsx
│   ├── activity-feed.tsx
│   └── ...
├── reports/                # Tier 2: Report composites
│   ├── team-leaderboard.tsx
│   ├── pipeline-velocity-cards.tsx
│   └── ...
└── layout/                 # Tier 2: Layout components
    ├── dashboard-sidebar.tsx
    ├── dashboard-header.tsx
    ├── notification-bell.tsx
    └── ...

Backend Infrastructure

lib/
├── supabase/
│   ├── client.ts           # Browser Supabase client
│   ├── server.ts           # Server Supabase client (reads cookies)
│   ├── admin.ts            # Service-role client (bypasses RLS)
│   └── middleware.ts       # Middleware Supabase client
├── actions/                # Next.js Server Actions
│   ├── auth.ts             # Login, register, logout, password reset
│   ├── contacts.ts         # Contact CRUD with full-text search
│   ├── companies.ts        # Company CRUD
│   ├── deals.ts            # Deal CRUD with stage updates
│   ├── pipelines.ts        # Pipeline and stage management
│   ├── tasks.ts            # Task CRUD
│   ├── activities.ts       # Activity log operations
│   ├── tags.ts             # Tag CRUD and entity tagging
│   ├── emails.ts           # Email send, read, star, delete
│   ├── email-templates.ts  # Template CRUD
│   ├── email-sequences.ts  # Sequence CRUD and enrollment
│   ├── team.ts             # Team member management
│   ├── notifications.ts    # Notification read/dismiss
│   ├── settings.ts         # CRM settings management
│   └── reports.ts          # Aggregate queries for analytics
├── schemas.ts              # Zod validation schemas
└── utils.ts                # Formatting, date helpers, constants

Database Files

supabase/
├── migrations/
│   ├── 001_schema.sql      # 19 tables with relationships and indexes
│   ├── 002_rls.sql         # Shared workspace RLS policies
│   ├── 003_triggers.sql    # Auto profile, updated_at, activity logging, last_contacted
│   └── 004_storage.sql     # crm-assets bucket for avatars and logos
└── seed.sql                # Team members, companies, contacts, deals, tasks, and more

Key Files

File	Purpose
middleware.ts	Protects all dashboard routes, redirects to /login
hooks/use-user.ts	Client hook for current user session
types/database.ts	Generated Supabase database types
types/index.ts	Application-level TypeScript interfaces
data/static.ts	Navigation items, onboarding steps (non-DB data)