Monorepo Structure - Winnerr CRM

Winnerr CRM is built as a modern monorepo using pnpm workspaces and Turborepo for efficient development, testing, and deployment. This architecture enables code sharing, consistent tooling, and streamlined development workflows across all applications and packages.

Repository Overview

winnerr-works/
├── 📱 apps/                    # Application layers
├── 📦 packages/               # Shared packages and libraries  
├── 🛠️ dev-docs/               # Development documentation
├── 🔧 .github/                # GitHub workflows and templates
├── 📋 package.json            # Root workspace configuration
├── 🚀 turbo.json             # Turborepo configuration
└── 🔒 pnpm-workspace.yaml    # Workspace definition

Applications (`apps/`)

Main CRM Application (`apps/app/`)

The core real estate CRM interface built with Next.js 15.

apps/app/
├── app/                       # Next.js App Router
│   ├── (authenticated)/      # Protected routes
│   │   ├── dashboard/         # Main dashboard
│   │   ├── people/           # Contact management
│   │   ├── deals/            # Deal pipeline
│   │   ├── properties/       # Property management
│   │   ├── phone/            # Communication hub
│   │   └── ai/               # AI features
│   ├── (unauthenticated)/    # Public routes
│   │   ├── sign-in/          # Authentication
│   │   └── sign-up/          # Registration
│   └── organization-setup/   # Organization onboarding
├── components/               # React components
│   ├── ai/                   # AI-specific components
│   ├── voice/                # Voice search components
│   └── ui/                   # UI components
├── hooks/                    # Custom React hooks
├── lib/                      # Utility functions
└── public/                   # Static assets

Key Features:

Next.js 15 App Router with React Server Components
Clerk authentication with multi-tenant organizations
Real-time collaboration with Liveblocks
AI-powered voice search and commands
Responsive design with shadcn/ui components

API Server (`apps/api/`)

Backend API services handling business logic and integrations.

apps/api/
├── app/
│   ├── api/                  # API routes
│   │   ├── auth/             # Authentication endpoints
│   │   ├── people/           # Contact management API
│   │   ├── deals/            # Deal management API
│   │   ├── properties/       # Property API
│   │   ├── twilio/           # Twilio integration
│   │   ├── nylas/            # Email/calendar integration
│   │   ├── ai/               # AI services
│   │   └── webhooks/         # Webhook handlers
│   └── webhooks/             # External webhook endpoints
├── lib/                      # Server utilities
│   ├── ai/                   # AI services
│   ├── analytics/            # Analytics services
│   ├── cache/                # Caching layer
│   └── services/             # Business logic
└── middleware.ts             # API middleware

Key Features:

RESTful API with OpenAPI documentation
Multi-tenant data isolation
Rate limiting and security middleware
Real-time WebSocket support
Comprehensive error handling and logging

Marketing Website (`apps/web/`)

Public-facing website for marketing and lead generation.

apps/web/
├── app/
│   ├── (home)/               # Landing page
│   ├── blog/                 # Blog and content
│   ├── pricing/              # Pricing information
│   ├── contact/              # Contact forms
│   └── legal/                # Legal pages
├── components/               # Marketing components
└── styles/                   # Marketing-specific styles

Documentation Site (`apps/docs/`)

This comprehensive documentation site built with Mintlify.

apps/docs/
├── mint.json                 # Mintlify configuration
├── introduction.mdx          # Home page
├── quickstart.mdx            # Getting started
├── architecture/             # Architecture documentation
├── features/                 # Feature guides
├── api-reference/            # API documentation
├── integrations/             # Integration guides
└── dev/                      # Developer resources

Chrome Extension (`apps/chrome-extension/`)

Browser extension for lead capture and CRM integration.

apps/chrome-extension/
├── src/
│   ├── background/           # Service worker
│   ├── content/              # Content scripts
│   ├── popup/                # Extension popup
│   └── sidepanel/            # Side panel interface
├── public/
│   └── manifest.json         # Extension manifest
└── scripts/                  # Build scripts

Key Features:

Lead capture from real estate websites
MLS data extraction
Direct CRM integration
Activity tracking and analytics

Email Templates (`apps/email/`)

React Email templates for transactional emails.

apps/email/
├── emails/                   # Email templates
│   ├── contact.tsx           # Contact notifications
│   ├── deal-update.tsx       # Deal notifications
│   └── welcome.tsx           # Welcome emails
└── components/               # Email components

Component Documentation (`apps/storybook/`)

Storybook for component documentation and testing.

apps/storybook/
├── stories/                  # Component stories
└── .storybook/               # Storybook configuration

Shared Packages (`packages/`)

Core Infrastructure

Database (`packages/database/`)

Centralized database schema and utilities using Prisma ORM.

packages/database/
├── prisma/
│   ├── schema.prisma         # Database schema
│   ├── migrations/           # Database migrations
│   └── seed.ts               # Seed data
├── lib/                      # Database utilities
└── types.ts                  # TypeScript types

Key Models:

User: Authentication and user preferences
Organization: Multi-tenant organization management
Person: Contact and lead management
Deal: Sales pipeline and commission tracking
Property: Real estate listings and MLS data
Communication: Unified communication tracking

Authentication (`packages/auth/`)

Clerk-based authentication with organization support.

packages/auth/
├── client.ts                 # Client-side auth utilities
├── server.ts                 # Server-side auth utilities
├── middleware.ts             # Auth middleware
├── components/               # Auth components
└── hooks/                    # Auth hooks

Design System (`packages/design-system/`)

Comprehensive UI component library built on shadcn/ui.

packages/design-system/
├── components/
│   ├── ui/                   # Base UI components
│   ├── communication/        # Communication components
│   └── visual/               # Visual components
├── hooks/                    # UI hooks
├── lib/                      # Utilities
└── styles/                   # Global styles

Business Logic Packages

AI Services (`packages/ai/`)

AI and machine learning capabilities.

packages/ai/
├── lib/
│   ├── sentiment-analysis.ts # Call sentiment analysis
│   ├── voice-commands.ts     # Voice command processing
│   └── lead-scoring.ts       # Enhanced lead scoring
└── components/               # AI UI components

Communication (`packages/twilio/`)

Twilio integration for voice and SMS.

packages/twilio/
├── lib/
│   ├── client.ts             # Twilio client
│   ├── voice.ts              # Voice call handling
│   ├── sms.ts                # SMS messaging
│   └── webhooks.ts           # Webhook processing
└── types/                    # TypeScript types

Analytics (`packages/analytics/`)

Analytics and tracking infrastructure.

packages/analytics/
├── posthog/                  # PostHog integration
├── hooks/                    # Analytics hooks
└── scripts/                  # Analytics utilities

Storage (`packages/storage/`)

File storage abstraction for R2/S3.

packages/storage/
├── lib/
│   ├── client.ts             # Storage client
│   ├── service.ts            # Storage service
│   └── types.ts              # Storage types
└── services/                 # Specialized storage services

Utility Packages

TypeScript Configuration (`packages/typescript-config/`)

Shared TypeScript configurations.

packages/typescript-config/
├── base.json                 # Base TypeScript config
├── nextjs.json               # Next.js specific config
└── react-library.json       # React library config

Tailwind Configuration (`packages/tailwind-config/`)

Shared Tailwind CSS configuration and utilities.

packages/tailwind-config/
├── config.ts                 # Main Tailwind config
├── typography.config.ts      # Typography configuration
└── index.ts                  # Exports

Workspace Configuration

Package Management (`pnpm-workspace.yaml`)

packages:
  - "apps/*"
  - "packages/*"

Build Orchestration (`turbo.json`)

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "outputs": ["coverage/**"]
    }
  }
}

Root Scripts (`package.json`)

{
  "scripts": {
    "dev": "turbo run dev --parallel",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "migrate": "pnpm --filter @repo/database db:migrate:dev",
    "studio": "pnpm --filter @repo/database db:studio"
  }
}

Dependency Management

Internal Dependencies

Packages reference each other using workspace protocols:

{
  "dependencies": {
    "@repo/database": "workspace:*",
    "@repo/auth": "workspace:*",
    "@repo/design-system": "workspace:*"
  }
}

External Dependencies

Framework: Next.js 15, React 18, TypeScript
Database: Prisma ORM, PostgreSQL
Authentication: Clerk
Styling: Tailwind CSS, shadcn/ui
Communications: Twilio, Nylas
Real-time: Liveblocks, Socket.IO
AI: OpenAI, custom ML models
Testing: Vitest, Testing Library
Deployment: Vercel, Docker

Development Workflow

Common Commands

# Install dependencies
pnpm install

# Start development
pnpm dev

# Build all packages
pnpm build

# Run tests
pnpm test

# Database operations
pnpm migrate
pnpm studio

# Linting and formatting
pnpm lint
pnpm format

Package-Specific Commands

# Work with specific packages
pnpm --filter @repo/database migrate
pnpm --filter apps/app dev
pnpm --filter @repo/design-system build

Architecture Benefits

Code Reusability

Shared components and utilities across applications
Consistent design system and patterns
Centralized business logic

Development Efficiency

Hot module reloading across packages
Parallel development and testing
Consistent tooling and standards

Maintenance

Single source of truth for dependencies
Coordinated releases and versioning
Simplified CI/CD pipelines

Scalability

Easy to add new applications or packages
Clear separation of concerns
Independent deployment capabilities

Package Interdependencies

Next Steps

Authentication Architecture

Learn about multi-tenant authentication and security

Database Design

Explore the complete database schema and relationships

API Architecture

Understand API design patterns and endpoints

This monorepo structure is designed to scale from individual developers to large teams while maintaining code quality, development velocity, and deployment reliability.

​Repository Overview

​Applications (apps/)

​Main CRM Application (apps/app/)

​API Server (apps/api/)

​Marketing Website (apps/web/)

​Documentation Site (apps/docs/)

​Chrome Extension (apps/chrome-extension/)

​Email Templates (apps/email/)

​Component Documentation (apps/storybook/)

​Shared Packages (packages/)

​Core Infrastructure

​Database (packages/database/)

​Authentication (packages/auth/)

​Design System (packages/design-system/)

​Business Logic Packages

​AI Services (packages/ai/)

​Communication (packages/twilio/)

​Analytics (packages/analytics/)

​Storage (packages/storage/)

​Utility Packages

​TypeScript Configuration (packages/typescript-config/)

​Tailwind Configuration (packages/tailwind-config/)

​Workspace Configuration

​Package Management (pnpm-workspace.yaml)

​Build Orchestration (turbo.json)

​Root Scripts (package.json)

​Dependency Management

​Internal Dependencies

​External Dependencies

​Development Workflow

​Common Commands

​Package-Specific Commands

​Architecture Benefits

​Code Reusability

​Development Efficiency

​Maintenance

​Scalability

​Package Interdependencies

​Next Steps

Authentication Architecture

Database Design

API Architecture

Repository Overview

Applications (`apps/`)

Main CRM Application (`apps/app/`)

API Server (`apps/api/`)

Marketing Website (`apps/web/`)

Documentation Site (`apps/docs/`)

Chrome Extension (`apps/chrome-extension/`)

Email Templates (`apps/email/`)

Component Documentation (`apps/storybook/`)

Shared Packages (`packages/`)

Core Infrastructure

Database (`packages/database/`)

Authentication (`packages/auth/`)

Design System (`packages/design-system/`)

Business Logic Packages

AI Services (`packages/ai/`)

Communication (`packages/twilio/`)

Analytics (`packages/analytics/`)

Storage (`packages/storage/`)

Utility Packages

TypeScript Configuration (`packages/typescript-config/`)

Tailwind Configuration (`packages/tailwind-config/`)

Workspace Configuration

Package Management (`pnpm-workspace.yaml`)

Build Orchestration (`turbo.json`)

Root Scripts (`package.json`)

Dependency Management

Internal Dependencies

External Dependencies

Development Workflow

Common Commands

Package-Specific Commands

Architecture Benefits

Code Reusability

Development Efficiency

Maintenance

Scalability

Package Interdependencies

Next Steps