NexusPlatform

NexusPlatform - Project Overview

1. Executive Summary & Problem Solved

NexusPlatform is a multi-tenant B2B SaaS application that enables organizations to manage team workspaces, control granular role-based access, track billing via Stripe, maintain comprehensive audit logs, and visualize business metrics through analytics dashboards.

Core Problems Addressed:

• Tenant Isolation: Secure data separation across organizations using tenant-scoped queries and middleware-level tenant resolution.
• Permission Complexity: A flexible RBAC system with resource-level permissions eliminates brittle role hierarchies.
• Billing Operations: Automated Stripe webhook handling for subscription lifecycle management (trial, upgrade, downgrade, cancellation, webhook retry resilience).
• Compliance & Accountability: Immutable audit logging captures every state-changing operation with actor context, timestamps, and before/after diffs.
• Data-Driven Decisions: Real-time analytics dashboards surface usage metrics, billing insights, and team activity.

---

2. Target Users & Value Proposition

User Role	Description	Value Delivered
Platform Admin	Super admin managing all tenants	Cross-tenant visibility, global config, system health
Org Admin	Manages a single organization	Tenant settings, member invites, billing management
Manager	Team lead within an org	Team analytics, member management (scoped), reporting
Member	Standard workspace user	Access assigned resources, personal productivity metrics
Billing Viewer	Restricted role	Read-only billing and invoice access

Value Proposition:

• Organizations onboard in minutes with self-service workspace creation and invite flows.
• Granular permissions (down to the route/resource level) reduce over-provisioning risk.
• Transparent billing with usage-based and tiered subscription models.
• Full audit trail satisfies SOC 2, GDPR, and internal compliance requirements.

---

3. Tech Stack & Architectural Decisions

Stack Overview

┌─────────────────────────────────────────────────┐
│                  Client Layer                    │
│  Next.js 14 (App Router) + Tailwind CSS         │
│  Recharts (analytics), react-hook-form (forms)  │
├─────────────────────────────────────────────────┤
│                 API Gateway                      │
│  Express.js (dedicated API server on :4000)     │
│  Middleware: auth, tenant resolution, RBAC      │
├─────────────────────────────────────────────────┤
│              Application Layer                   │
│  Next.js Server Actions + API Routes (:3000)    │
│  Service modules (billing, auth, audit, etc.)   │
├─────────────────────────────────────────────────┤
│                Data Layer                        │
│  MongoDB (native driver — no ODM)               │
│  Collections: users, orgs, teams, roles,        │
│               audit_logs, subscriptions         │
├─────────────────────────────────────────────────┤
│              External Services                   │
│  Stripe (billing), NextAuth.js (auth)           │
│  Redis (optional: caching, rate limiting)       │
└─────────────────────────────────────────────────┘

Rationale for Key Choices

Decision	Rationale
Next.js App Router	Unified framework for SSR, SSG, API routes, and Server Actions — reduces boilerplate, enables progressive enhancement, and keeps auth/billing logic server-side.
Native MongoDB Driver	Direct driver access avoids ODM overhead (no Mongoose/Prisma), provides full query operator access, and yields ~40% lower latency on complex aggregations for analytics. Schema validation handled via runtime validation (Zod) at service boundaries.
Express.js as API Gateway	Dedicated API server cleanly separates webhook endpoints (Stripe), third-party integrations, and health checks from the Next.js app. Middleware chain (auth → tenant → RBAC) applies uniformly.
Tailwind CSS	Utility-first approach enables rapid, consistent UI development without context-switching. Custom tailwind.config.ts theme tokens enforce design system across all tenant-facing views.
No Redux/Zustand	Next.js Server Components handle data fetching server-side. Client state is minimal — managed via React Context for auth/session and react-hook-form for form state. Server Actions mutate state, eliminating the need for client-side stores.
Zod for Validation	Lightweight, TypeScript-native schema validation at API boundaries and service layer. Replaces Mongoose schemas and Prisma Zod schemas while providing compile-time type inference.
Recharts	Composable, SVG-based charting library integrates cleanly with Next.js and Tailwind. Supports all dashboard requirements (bar, line, pie, area charts) with minimal bundle impact.

Architecture Diagram

Browser → Next.js (:3000) ──┬── Server Pages (SSR with tenant context)
                             ├── Server Actions (mutations)
                             └── API Routes (REST)
                                      │
                              Express (:4000) ◄── Stripe Webhooks
                                      │
                              ┌───────┴───────┐
                              │  Middleware    │
                              │  1. JWT Auth   │
                              │  2. Tenant ID  │
                              │  3. RBAC Check │
                              └───────┬───────┘
                                      │
                              Service Layer (Zod-validated)
                                      │
                              ┌───────┴───────┐
                              │  MongoDB       │
                              │  (native driver│
                              │   with MQL)    │
                              └───────────────┘

---

4. Repository Quickstart & Environment Setup

Project Structure

nexus-platform/
├── apps/
│   ├── web/                    # Next.js application
│   │   ├── app/
│   │   │   ├── (auth)/         # Login, register, forgot password
│   │   │   ├── (dashboard)/    # Protected layouts
│   │   │   │   ├── org/[orgId]/
│   │   │   │   │   ├── team/
│   │   │   │   │   ├── billing/
│   │   │   │   │   ├── analytics/
│   │   │   │   │   ├── settings/
│   │   │   │   │   └── audit/
│   │   │   │   ├── admin/      # Platform admin views
│   │   │   │   └── api/        # Next.js API routes
│   │   │   ├── layout.tsx
│   │   │   └── globals.css
│   │   ├── components/
│   │   │   ├── ui/             # shadcn/ui base components
│   │   │   ├── dashboard/      # Chart & metric components
│   │   │   ├── forms/          # Reusable form components
│   │   │   └── shared/         # Navbar, sidebar, modals
│   │   ├── lib/
│   │   │   ├── mongo.ts        # MongoDB connection singleton
│   │   │   ├── auth.ts         # NextAuth configuration
│   │   │   ├── rbac.ts         # Permission checking utilities
│   │   │   ├── audit.ts        # Audit log writer
│   │   │