Compass SaaS — Documentation Index

Compass is a multi-tenant SaaS CRM for Indian real estate vendors. It is a sales-led platform: vendors are provisioned by the platform team after KYC and payment, and then run their full lead-management workflow from a single tenant-scoped admin app.

---

Table of Contents

Core

Document	Description
Architecture Overview	High-level system design and component interactions
Multi-Tenancy	Tenant isolation primer, guards, and limit policy
Tenant Lifecycle	Sales-led onboarding: prospect → KYC → invoice → payment → activation
Database Schema	Prisma models, enums, and indexing strategy
Data Flows	End-to-end walkthroughs of key user journeys
Plans & Feature Flags	Plan catalog (LAUNCH / SCALE / PRO), limits, DevCycle gating, upgrade flow

Backend (NestJS)

Document	Description
Backend Overview	Server bootstrap, global config, request lifecycle
Modules	Every NestJS module with controller/service responsibilities
API Endpoints	REST API reference grouped by resource
Authentication & Identity	Kratos, Hydra, magic-link activation, mobile-OTP
Feature Flags	DevCycle wiring (server + client), per-tenant overrides
Background Jobs	BullMQ queues, processors, and schedulers
Lead Scoring	PostHog-driven scoring algorithm
Lead Assignment	Rules engine and team policies

Frontend (Next.js)

Document	Description
Admin App	Vendor-facing dashboard (sales teams)
Super-Admin App	Platform admin (tenant provisioning, KYC, billing)

Infrastructure

Document	Description
Docker	Compose services, volumes, networking
Nginx & SSL	Reverse proxy and domain routing
Dokploy Deploy	VPS deployment via Dokploy

Reference

Document	Description
Events & Lead Scoring	PostHog event catalog and score tables
Legal	Privacy / terms reference text
Color Reference / Usage Guide	Design system colors

---

Quick-Start Summary

Repository Layout

compass-saas/
├── server/         # NestJS REST API (port 8000)
├── admin/          # Next.js vendor dashboard (port 3000)
├── super-admin/    # Next.js platform admin (port 3001)
├── web/            # Marketing/intake site (demo request form)
├── kratos/         # Ory Kratos config + identity schema
├── hydra/          # Ory Hydra config
├── nginx/          # Reverse proxy + TLS
├── init-db/        # PostgreSQL bootstrap scripts (kratos + hydra DBs)
├── infra/          # Dokploy + supporting infra docs
├── docs/           # ← This documentation
└── docker-compose*.yml

Tech Stack

Layer	Technology
Backend API	NestJS 11, TypeScript, Prisma 5, PostgreSQL 16
Background Jobs	BullMQ 5 + Redis 7
Admin / Super-Admin UI	Next.js 16, React 19, Tailwind, shadcn/ui, TanStack Query, Zustand
Identity	Ory Kratos (sessions)
OAuth2	Ory Hydra (token issuance with tenant claims)
Feature Flags	DevCycle via OpenFeature (server + client SDKs)
File Storage	Cloudinary (default) or AWS S3 (configurable)
Email	SendGrid + Handlebars templates
Analytics (events)	PostHog (lead scoring inputs)
Authorization	Server: dynamic RBAC with policy_version; Client: CASL ability + RequireFeature gates
Reverse Proxy	Nginx + Let's Encrypt

Production Domains

URL	Service
compass.xlr8codes.in	Admin app (3000)
sudo.compass.xlr8codes.in	Super-admin app (3001)
api.compass.xlr8codes.in	NestJS API (8000)
auth.compass.xlr8codes.in	Ory Kratos (4433)

---

Key Concepts

Sales-Led Tenant Lifecycle

Self-signup is retired. New vendors enter as Prospects, are guided through KYC document upload → invoice → payment → activation, and only then receive a magic-link activation email. State machine:

PROSPECT → KYC_PENDING → KYC_APPROVED → INVOICED → PAYMENT_PENDING
       → PARTIALLY_PAID → ACTIVATING → ACTIVE → AMC_PENDING / SUSPENDED / CHURNED / ARCHIVED

Plan Catalog (PlanCode enum)

Code	Tier
LAUNCH	Entry — core CRM only
SCALE	Growth — adds advanced reports, automation rules, communication tracking, exports, predefined RBAC
PRO	All features — workflows + SLA, custom roles, audit logs, integrations, API access

Plan limits (max users / leads / projects) live on Plan; per-tenant overrides on Subscription.extra_users / Subscription.extra_leads. See Plans & Feature Flags.

Lead Lifecycle

NEW → INTERESTED → SITE_VISIT_SCHEDULED → SITE_VISIT_DONE → NEGOTIATION → QUALIFIED
                                                                       → LOST
                                                                       → JUNK

Authorization

Server-side dynamic RBAC: TenantRole × Permission (resource:action) × UserRole (with scope: TENANT | COMPANY | PROJECT | TEAM) + UserPermission overrides. Tenants have a policy_version that the admin client polls to detect permission changes. Plan-feature gates use DevCycle (@RequireFeature(...) server, usePlanFeature(...) client).

Multi-Step Workflows + SLA

WorkflowDefinition → WorkflowSteps execute via the workflow.execute queue on lead triggers. SlaPolicy defines target response times; the workflow.sla watcher escalates on breach. Gated by the multi_step_workflows and sla_configuration features.

---

Running Locally

# 1. Configure env files in server/, admin/, super-admin/
# 2. Bring up the stack
docker compose up -d

# 3. Run migrations
docker compose exec server npx prisma migrate deploy

# 4. Seed plan catalog + super-admin
docker compose exec server npx ts-node src/scripts/seed-super-admin.ts

See DEPLOY_ON_VPS.md for full VPS deployment.