🏗️ CRM Platform - Technical Documentation

Note to Recruiters: This documentation provides a high-level overview of the CRM architecture, technical decisions, and feature set. It is intended to demonstrate system design capabilities and full-stack proficiency.

🚀 Project Overview

This is a Multi-Tenant, Industry-Agnostic CRM Platform designed to be highly customizable for various business sectors (Real Estate, Legal, Sales, etc.).

Why this builds? Most CRMs are either too generic (Salesforce) or too niche (Clio for Law). This platform solves that by using a Metadata-Driven Architecture. The "Entities" (Contacts, Deals, Properties) are not hardcoded but defined in the database, allowing specific "Industries" to have their own terminology, fields, and workflows without changing the code.

🛠️ Technology Stack

Frontend (@crm/web)

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS + Radix UI (Headless components)
• State Management: Zustand (Global store) + TanStack Query (Server state)
• Forms: React Hook Form + Zod validation
• Drag & Drop: @dnd-kit (for Kanban boards)

Backend (@crm/api)

• Framework: NestJS (Modular architecture)
• Runtime: Node.js
• Database ORM: Prisma (PostgreSQL)
• Authentication: Passport.js (JWT + Google OAuth 2.0)
• Queue/Async: Redis (BullMQ via wrappers) - Planned/Partial
• Validation: Class-Validator + DTOs

Infrastructure & DevOps

• Monorepo Tool: Turborepo
• Containerization: Docker & Docker Compose
• Database: PostgreSQL 16
• Cache: Redis 7
• Mail: MailHog (Local dev)

---

🏛️ System Architecture

The project follows a Monorepo structure to share code effectively between the API and Client.

/
├── apps/
│   ├── web/          # Next.js Frontend Application
│   └── api/          # NestJS Backend API
├── packages/
│   ├── types/        # Shared TypeScript Interfaces/DTOs
│   ├── config/       # Shared Constants & ENV parsing
│   ├── ui/           # Shared React Component Library (Design System)
│   └── utils/        # Shared Helper functions
├── prisma/           # Database Schema & Migrations
└── docker-compose.yml

---

💾 Data Modeling (ER Diagram)

The core strength of this system is its relationship model. It uses a Multi-Tenant strategy where data is isolated by Workspace.

Loading Diagram...

Key Design Decisions:

1. JSONB for Flexibility: The Record table uses a data JSONB column. This allows us to store dynamic fields defined by the Entity metadata without altering the database schema for every new customer field.
2. RBAC (Role-Based Access Control): Permissions are granular (e.g., contacts.view, contacts.edit) and assigned to Roles, which are then assigned to WorkspaceMembers.

---

⚡ Data Flow & Logic

1. Authentication Flow (Hybrid)

We support both standard Email/Password and Google OAuth.

Loading Diagram...

2. Request Lifecycle (NestJS)

Every API request goes through a strict pipeline to ensure security and validation.

1. Guard: Checks Access-Token (JWT). Validation fails -> 401.
2. Interceptor: Adds User context to request.
3. Pipe: Validates input body against DTOs (Data Transfer Objects) using zod or class-validator.
4. Controller: Routes request to correct service.
5. Service: executing business logic (e.g., "Create Workspace").
6. Repository (Prisma): interactions with DB.

---

🌟 Key Features Implemented

Module	Status	Description
Auth	✅	JWT, Google OAuth, Session Management
Multi-Tenancy	✅	Workspace creation, switching, member management
Dynamic CRM	✅	Creating Records based on metadata (Entity/Field definitions)
Automation	🚧	Event-driven triggers (Create Record -> Send Email). Queue implemented.
Billing	🚧	Stripe Integration models prepared (Subscription, Invoice)
RBAC	✅	Role & Permission Guard system
Audit Logs	✅	Tracking who did what (IP, User Agent, Action)

---

🧪 Future Improvements

• Websockets: Real-time updates for Kanban boards.
• AI Integration: Using the OpenAI API to summarize CRM records (foundations in place).
• Mobile App: React Native app sharing packages/types and packages/client.