NexusPlatform - Project Overview

1. Executive Summary & Problem Solved

NexusPlatform is a multi-tenant B2B SaaS platform that enables organizations to manage team workspaces, control granular user permissions, track billing via Stripe, maintain immutable audit logs, and visualize business metrics through analytics dashboards. It solves the core challenge of securely isolating tenant data while providing a unified admin experience with real-time billing transparency and compliance-grade audit trails.

Key problems addressed:

• Tenant isolation — Strict data partitioning ensuring no cross-tenant data leakage at the application or query level.
• Authorization complexity — RBAC + resource-level permissions replacing brittle isAdmin boolean checks.
• Billing reliability — Robust Stripe integration with webhook signature verification, idempotency, and subscription lifecycle management.
• Compliance — Append-only audit log capturing every mutation with actor context, timestamps, and before/after diffs.
• Analytics latency — Pre-aggregated MongoDB pipeline queries served through cached dashboard endpoints.

---

2. Target Users & Value Proposition

User Role	Description	Value Delivered
Platform Admin	SaaS operator managing all tenants	Full tenant overview, billing management, system-wide audit trail
Organization Admin	Lead user within a tenant workspace	Manage team members, assign roles, configure workspace settings
Member	Standard workspace user	Access assigned resources, view personal activity
Billing Viewer	Finance stakeholder	Invoice history, payment status, usage metrics

Value proposition per persona:

• Admins get a single pane of glass across tenants with instant role/permission changes propagated via session revalidation.
• Finance teams see real-time subscription health without logging into Stripe.
• Members experience a fast, permission-aware UI that only renders actions they are authorized to perform.

---

3. Tech Stack & Architectural Decisions (Rationale)

Architecture: Monorepo with Bounded Contexts

nexus-platform/
├── apps/
│   ├── web/              # Next.js 16 (App Router) — UI + Server Actions
│   └── api/              # Express 5 — API gateway, Stripe webhooks, SSE
├── packages/
│   ├── db/               # MongoDB native driver connection + typed collections
│   ├── auth/             # Session management, cookie handlers, RBAC guards
│   ├── shared/           # Zod schemas, types, constants, utilities
│   └── ui/               # Tailwind CSS v4 component primitives
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

Stack Decisions

Technology	Choice	Rationale
Next.js 16	Frontend + Server Actions	App Router enables layout-based tenant routing (/[tenant]/dashboard), Server Components reduce client JS, Server Actions handle mutations without API route boilerplate.
Express 5	Dedicated API layer	Separates concerns from Next.js — handles Stripe webhook signature verification (requires raw body), streaming responses for analytics, and long-running operations. Native async error handling in v5 reduces middleware boilerplate.
MongoDB (native driver)	Database	Direct driver access avoids ORM/ODM overhead. Type safety achieved via Zod validation schemas at repository layer. Aggregation pipelines power analytics natively. No schema migration friction.
Tailwind CSS v4	Styling	CSS-first configuration via @theme directive, zero-runtime, native dark mode support, seamless integration with Next.js App Router layout system.
Stripe	Billing	Industry-standard subscription management. Webhook-driven event processing ensures eventual consistency between Stripe state and internal billing records.
Session Auth (custom)	Authentication	Server-side sessions stored in MongoDB with opaque tokens in httpOnly, SameSite=Strict, Secure cookies. No JWT bloat — sessions are revocable instantly by deleting the session record.
TanStack Query	Client state	Server-state management without Redux/Zustand. Automatic cache invalidation on mutations, optimistic updates, and stale-while-revalidate patterns align with Next.js Server Component data fetching.
Zod	Validation	Runtime type validation bridging TypeScript types and runtime data (MongoDB documents, API inputs, Stripe payloads). Single source of truth for types.
Recharts	Analytics visualization	Lightweight, React-native SVG charts. Composable with Tailwind styling. No heavy charting runtime.

Why NOT the excluded technologies:

• No Redux/Zustand: TanStack Query manages server state; React useState/useReducer + Context handle local UI state. This eliminates unnecessary client-side complexity for a server-rendered app.
• No Mongoose: Native MongoDB driver with Zod schemas provides equivalent type safety without schema rigidity, middleware chains, or the 7MB+ dependency footprint.
• No Prisma: Native driver keeps bundle size lean, gives direct access to aggregation pipelines, and avoids the schema definition language layer that adds coupling.

---

4. Repository Quickstart & Environment Setup

Prerequisites

• Node.js ≥ 22 LTS
• pnpm ≥ 9
• MongoDB ≥ 7 (local or Atlas URI)
• Stripe account (test mode)

Clone & Install

git clone <repo-url> nexus-platform
cd nexus-platform
pnpm install
pnpm turbo dev --filter=web --filter=api

Environment Variables

Apps/Web — .env.local

# Next.js 16
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Auth (cookie signing)
AUTH_SECRET=change-me-to-a-256-bit-random-string
AUTH_SESSION_MAX_AGE=86400
AUTH_COOKIE_DOMAIN=localhost

# MongoDB (web layer uses for Server Actions fallback)
MONGODB_URI=mongodb://localhost:27017/nexus-web

# Tenant defaults
DEFAULT_PLAN_ID=plan_basic

Apps/API — .env.local

# Express 5
PORT=3001
NODE_ENV=development

# MongoDB (primary data layer)
MONGODB_URI=mongodb://localhost:27017/nexus-api

# Stripe
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_WEBHOOK_PORT=3001

# Auth
AUTH_SECRET=change-me-to-a-256-bit-random-string
AUTH_SESSION_MAX_AGE=86400
AUTH_COOKIE_DOMAIN=localhost

# Security
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=100

# Analytics cache
ANALYTICS_CACHE_TTL=300

Port Conventions

Service	Port	Purpose
Web (Next.js)	3000	Main application, SSR, Server Actions
API (Express 5)	3001	REST API, Stripe webhooks, SSE streams
MongoDB	27017