> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winnerr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monorepo Structure

> Deep dive into Winnerr's monorepo architecture, package organization, and dependency management

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`)

```yaml theme={null}
packages:
  - "apps/*"
  - "packages/*"
```

### Build Orchestration (`turbo.json`)

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

### Root Scripts (`package.json`)

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
# 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

```bash theme={null}
# 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

```mermaid theme={null}
graph TB
    A[apps/app] --> B[packages/auth]
    A --> C[packages/database]
    A --> D[packages/design-system]
    A --> E[packages/ai]
    
    F[apps/api] --> B
    F --> C
    F --> G[packages/twilio]
    F --> H[packages/storage]
    F --> E
    
    I[apps/chrome-extension] --> C
    I --> B
    
    D --> J[packages/tailwind-config]
    D --> K[packages/typescript-config]
    
    B --> C
    E --> C
    G --> C
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication Architecture" icon="shield-check" href="/architecture/authentication">
    Learn about multi-tenant authentication and security
  </Card>

  <Card title="Database Design" icon="database" href="/architecture/database-design">
    Explore the complete database schema and relationships
  </Card>

  <Card title="API Architecture" icon="code" href="/architecture/api-architecture">
    Understand API design patterns and endpoints
  </Card>
</CardGroup>

***

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