Architecture Overview

winnerr-works/
├── apps/                    # Application layers
│   ├── app/                # Main CRM application (Next.js 15)
│   ├── api/                # Backend API services
│   ├── web/                # Marketing website
│   ├── docs/               # This documentation site
│   ├── email/              # Email templates (React Email)
│   ├── storybook/          # Component documentation
│   └── chrome-extension/   # Browser extension for lead capture
├── packages/               # Shared packages
│   ├── ai/                 # AI services and components
│   ├── analytics/          # Analytics and tracking
│   ├── auth/               # Authentication (Clerk)
│   ├── database/           # Prisma schema and utilities
│   ├── design-system/      # shadcn/ui components
│   ├── mcp/                # Model Context Protocol
│   ├── notifications/      # Push notifications
│   ├── payments/           # Stripe integration
│   ├── storage/            # R2/S3 file storage
│   └── twilio/             # Phone and SMS services
└── dev-docs/              # Development documentation

// Standard API route pattern
export async function POST(req: Request) {
  // 1. Authentication & organization context
  const { userId, orgId } = await auth();
  
  // 2. Input validation with Zod
  const data = requestSchema.parse(await req.json());
  
  // 3. Business logic with proper error handling
  const result = await businessLogic(data, { userId, orgId });
  
  // 4. Structured response with CORS
  return NextResponse.json(result, { headers: corsHeaders });
}

// Event system for real-time updates
export const eventBus = {
  emit: (event: string, data: unknown, orgId: string) => {
    // Emit to organization-specific channels
    io.to(`org:${orgId}`).emit(event, data);
    
    // Log for analytics
    analytics.track(event, data, { orgId });
  }
};

-- Example: People table with organization isolation
CREATE TABLE "Person" (
  "id" TEXT PRIMARY KEY,
  "organizationId" TEXT NOT NULL,
  "firstName" TEXT,
  "lastName" TEXT,
  "email" TEXT,
  "phone" TEXT,
  "createdAt" TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  FOREIGN KEY ("organizationId") REFERENCES "Organization"("id")
);

-- Row-level security policy
CREATE POLICY person_isolation ON "Person"
  FOR ALL USING (
    "organizationId" = current_setting('app.current_organization')
  );

// Real-time presence system
class PresenceManager {
  private connections = new Map<string, Set<string>>();
  
  joinOrganization(userId: string, orgId: string) {
    // Add user to organization room
    this.connections.get(orgId)?.add(userId);
    
    // Broadcast presence update
    this.broadcastPresence(orgId);
  }
  
  broadcastPresence(orgId: string) {
    const users = Array.from(this.connections.get(orgId) || []);
    io.to(`org:${orgId}`).emit('presence:update', { users });
  }
}

interface LeadScoringFactors {
  behavioralScore: number;    // Website interactions, email opens
  engagementScore: number;    // Response rates, call duration
  demographicScore: number;   // Location, property preferences
  timelineScore: number;      // Urgency indicators
  sourceScore: number;        // Lead source quality
}

class EnhancedLeadScoring {
  calculateScore(person: Person, factors: LeadScoringFactors): number {
    // AI-powered scoring algorithm
    return this.aiModel.predict({
      ...factors,
      historicalData: person.interactions,
      marketConditions: this.getMarketData(person.location)
    });
  }
}

// Analytics event tracking
analytics.track('deal_created', {
  dealValue: deal.amount,
  propertyType: deal.property.type,
  leadSource: deal.person.source,
  agentId: deal.assignedTo,
  organizationId: deal.organizationId
});