nexus-orbit-saas-lite — Next.js SaaS Template

SHA-256: fa2daa562d3cd5d0ab008748a0948b0fecb830352b6e9035862dafe74cb79071

2026-10-03T02:58:48.795Z

# NexusOrbit SaaS Lite (Next.js)

**NexusOrbit-Lite** is the public, conversion-focused surface of the NexusOrbit product line: a **Next.js App Router** + **React 19** + **MUI v7** shell that mirrors the Pro marketing experience while isolating premium logic behind a clean upgrade path. This repository is engineered to signal **discipline, depth, and delivery**—the same architectural standards that power the full boilerplate.

## Links

### Lite version (this repository)

- **Lite version live URL:** [https://nexus-orbit-saas-lite.vercel.app/](https://nexus-orbit-saas-lite.vercel.app/)
- **Lite version GitHub repository:** [https://github.com/ShuvaMallickPro/nexus-orbit-saas-lite](https://github.com/ShuvaMallickPro/nexus-orbit-saas-lite)

### Pro product (full boilerplate)

- **Live (Pro):** [https://www.nextsaaspilot.com/](https://www.nextsaaspilot.com/)

> **Lite:** demos, static marketing blocks, and upgrade CTAs. **Pro:** full SaaS stack—auth, Prisma, Stripe, S3, dashboards, and production workflows.

---

## 1. Comprehensive feature comparison (Pro vs. Lite)

| Feature                  | Lite Version                                                                                           | Pro Version                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **UI Design**            | Mock / Static UI (preview imagery, glass overlays, marketing-safe blocks)                              | Production ready / Full logic (dynamic sections, interactive data surfaces, full component depth)     |
| **Authentication**       | Mock / Static UI (demo-oriented flows where applicable)                                                | Production ready / Full logic (NextAuth, credentials + OAuth, hardened session strategy)              |
| **Database integration** | Mock / Static UI (no persistent product data path on the lite surface)                                 | Production ready / Full logic (Prisma, migrations, type-safe access patterns)                         |
| **S3 file storage**      | Mock / Static UI                                                                                       | Production ready / Full logic (private buckets, presigned URLs, lifecycle-aware object handling)      |
| **Stripe payments**      | Mock / Static UI (checkout CTAs routed to your payment URL; no live billing coupling on the lite path) | Production ready / Full logic (checkout sessions, customer portal, subscription lifecycle)            |
| **Deployment**           | Mock / Static UI (static-friendly marketing build; minimal moving parts)                               | Production ready / Full logic (environment matrix, secrets, webhooks, observability-ready deployment) |

### Lite-specific configuration

- **Upgrade / checkout URL:** set `NEXT_PUBLIC_YOUR_PAYMENT_URL` in `.env` (fallback in code: `YOUR_PAYMENT_URL`). Hero and pricing CTAs use this value—see `src/config.ts` (`YOUR_PAYMENT_URL`, `appConfig.salesLink`).
- **Static section previews:** place screenshots under `public/lite/` (e.g. feature / value-prop / wall-of-love assets) and align paths in `src/components/sections/*/index.tsx` with your filenames.

---

## Highlights

- **Modern Next.js stack**: App Router, Server Components by default, Server Actions where appropriate
- **UI system**: MUI v7 + Emotion, with a consistent theme layer (`src/theme/`)
- **Auth (Pro path)**: NextAuth (JWT session strategy), credentials + OAuth providers
- **Database (Pro path)**: Prisma ORM (type-safe queries and schema-driven migrations)
- **Forms**: React Hook Form + Zod validation
- **Uploads (Pro path)**: AWS S3 storage support (recommended: private bucket + presigned URLs)
- **DX**: TypeScript, ESLint, strong folder conventions

## Tech stack

- **Framework**: Next.js 16+
- **UI**: Material UI (MUI) v7, Emotion
- **Auth**: NextAuth
- **DB**: Prisma
- **Validation**: Zod
- **Forms**: React Hook Form
- **Payments**: Stripe

## Project structure

Key folders (under `src/`):

- **`src/app/`** — App Router routes, layouts, and route handlers
- **`src/actions/`** — Server Actions (`"use server"`) for mutation workflows
- **`src/components/`** — UI components and feature modules (including `src/components/lite/` for Lite previews)
- **`src/lib/`** — Shared logic (auth helpers, Prisma client, S3 helpers, utilities)
- **`src/theme/`** — Theme configuration and MUI customization

---

## 2. Architectural challenges & decisions

The items below are framed as **engineering achievements**—decisions made under real constraints, expressed using the **STAR** method (**Situation**, **Task**, **Action**, **Result**).

### A) Advanced MUI engineering

- **Situation:** The Pro product required dense marketing surfaces—an **advanced bento grid**, asymmetric card spans, and **multi-theme hover logic**—without fragmenting the design system or breaking readability across alternating sections.
- **Task:** Preserve **visual hierarchy** when backgrounds and elevation shift between light-forward and dark-forward regions, while keeping hover/focus behavior predictable for accessibility and brand consistency.
- **Action:** Standardized layout primitives on **MUI theme tokens** (`palette`, `alpha`, spacing, typography ramps) and `styled()` boundaries so elevation, borders, and hover transitions resolve from the theme—not ad hoc hex values. Complex grids were composed from repeatable card contracts rather than one-off CSS overrides.
- **Result:** A **single source of truth** for contrast and motion: components read intent from the theme, marketing sections stay coherent across modes, and future palette adjustments propagate without surgical rewrites.

### B) Security & data integrity (NextAuth edge cases)

- **Situation:** OAuth (Google) sign-in and manual (email/password) registration can produce **duplicate identity rows** if linking rules are naive—especially when the same human returns through a different front door.
- **Task:** Guarantee **one canonical user row** per identity while preserving auditability and preventing credential confusion when a Google-first user later attempts manual registration.
- **Action:** Implemented an account **merge/linking policy** that reconciles OAuth identities with existing records using verified email as the stable join key, plus a **passwordless guard** that blocks contradictory manual registration paths for Google-authenticated identities. Session callbacks were tightened to **cache stable session fields** and avoid redundant database round-trips on hot paths.
- **Result:** Fewer integrity incidents, cleaner auth graphs, and a session layer that stays **fast without being sloppy**—security rules remain explicit, not accidental.

### C) Synchronous infrastructure (S3 & Prisma)

- **Situation:** File metadata can disappear from the database while objects remain in object storage—an **architectural hurdle** that creates **dangling storage** and silent cost leakage over time.
- **Task:** Make deletion semantics **economically honest**: when a file record is removed, the object store must not drift into orphaned assets.
- **Action:** Designed **cloud–DB sync** semantics where authoritative deletion in Prisma triggers a **synchronous cleanup** in S3 (with explicit error handling and idempotent guards where appropriate), so storage state tracks application truth.
- **Result:** A storage posture aligned with production finance: fewer surprises in billing, fewer “ghost assets,” and a clearer operational story for support and compliance reviews.

### D) Payment pipeline & webhook reliability

- **Situation:** Stripe integrations often fail in subtle ways—signature mismatches, replay issues, and “works on my machine” webhook behavior when local environments can’t observe real events.
- **Task:** Build a **webhook listener** that is deterministic under retries, safe under partial failures, and trustworthy during local iteration.
- **Action:** Implemented a robust listener with **signature verification** as a non-negotiable gate, structured event handling, and **Stripe CLI**-driven local forwarding so developers observe **real-time event synchronization** against the same verification rules used in production.
- **Result:** An integration posture that converts a common integration hurdle into a **stable payment bridge**: fewer false positives, faster debugging, and a deployment story that scales from laptop to production without rewriting assumptions.

---

## 3. Closing statement

These challenges sharpened the same muscle that defines serious SaaS work: **turn ambiguous requirements into explicit contracts**, **treat auth and billing as systems—not features**, and **optimize for operational truth** (storage, sessions, and payments) rather than demo aesthetics alone. NexusOrbit-Lite exists to showcase that mindset in public—**tight UI engineering**, **defensive identity modeling**, **storage integrity**, and **payment plumbing you can trust**—while Pro delivers the full execution stack for teams who ship under real constraints.

---

## Getting started

### Prerequisites

- Node.js **20+** (recommended)
- npm / pnpm / yarn (examples below use **npm**)

### Install

```bash
npm install
```

### Environment variables

Create a `.env` file in the project root. Typical keys include:

**Lite / marketing**

- `NEXT_PUBLIC_YOUR_PAYMENT_URL` — checkout or sales page for upgrade CTAs
- `NEXT_PUBLIC_SALES_LINK` — optional; aligns with sales/upgrade messaging in `appConfig`
- `NEXT_PUBLIC_APP_URL` / `AUTH_URL` — app base URL where applicable

**Auth**

- `NEXTAUTH_SECRET`
- `NEXTAUTH_URL`
- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (optional)

**Database (Prisma) — Pro workflows**

- `DATABASE_URL`

**Stripe (optional / Pro)**

- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`

**AWS S3 (optional / Pro uploads)**

- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `AWS_REGION`
- `AWS_S3_BUCKET_NAME`

> If you change the Prisma schema, run `npx prisma generate`.

### Run dev server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000).

---

## Common workflows

### Lint

```bash
npm run lint
```

### Build & start

```bash
npm run build
npm run start
```

---

## Uploads (S3) — recommended approach (Pro)

This project supports storing user-uploaded files in S3.

- **Recommended:** keep the S3 bucket **private** and display assets using **presigned GET URLs**.
- **Avoid:** making user uploads public unless you fully understand the data exposure trade-off.

---

## Deployment

You can deploy on any platform that supports Node + Next.js. For Vercel, see the [Next.js deployment docs](https://nextjs.org/docs/app/building-your-application/deploying).

---

## Contributing

Issues and PRs are welcome. Please include:

- a short problem statement
- screenshots (for UI changes)
- steps to reproduce (for bugs)

---

## License

See the repository license file (if provided).