🧱 Architecture Overview

SaaSKit is a modern SaaS framework built on a clean and modular full-stack architecture. It leverages powerful open-source tools such as Next.js 15.3, React 19, Supabase, and Prisma to help developers build and scale SaaS applications rapidly and efficiently.

---

🧭 Core Architectural Principles

• Modularity: Code is organized by feature and responsibility. UI components, server actions, and backend logic are clearly separated and reusable.
• Server-first: Built with Next.js Server Actions, enabling backend logic to live alongside your frontend code — no need for separate API routes.
• Strong typing: Full TypeScript support across the stack, ensuring type safety from database to UI.
• Security by design: Integrates Supabase Row-Level Security (RLS) and role-based route protection.
• Responsive-first UI: Layout components are mobile-friendly, with built-in support for dark mode and breakpoints.

---

🗂 Directory Structure Overview

/app/
  layout.tsx             → App-wide layout: Sidebar + Topbar
  /dashboard              → Main dashboard page
  /auth/login             → Authentication UI
  /settings               → User settings
  /admin                  → Admin-only routes (protected)

components/
  /layout/Sidebar.tsx     → Responsive sidebar navigation
  /layout/Topbar.tsx      → Topbar with logo, profile, and actions
  /ui/                    → Buttons, Cards, Tables, Inputs, etc.

lib/
  prisma.ts               → Prisma Client config
  supabase.ts             → Supabase Client config
  auth.ts                 → User session and role helpers

app/actions/              → Server Actions (form logic, DB queries)

prisma/
  schema.prisma           → Data models (User, Role, Team, etc.)

.env.local                → Environment secrets (Supabase, JWT, etc.)

---

🔐 Authentication & Authorization

SaaSKit uses Supabase Auth for login via Email and OAuth. Authorization is enforced in two layers:

1. Frontend: Middleware validates user roles and redirects unauthorized users.
2. Database: Supabase Row-Level Security (RLS) ensures users can only access their own records.

User sessions are accessible in Server Actions, allowing secure backend logic without exposing APIs.

---

🔄 Data Flow Lifecycle

1. User logs in via Supabase (email or OAuth).
2. Session is stored and retrieved on the server.
3. Server Actions are triggered via form or component interactions.
4. Data is fetched or mutated using Prisma.
5. UI updates with React 19 and Server Components.

This approach enables secure, real-time, full-stack interactivity without needing a traditional REST or GraphQL API.

---

🧰 Tech Stack Breakdown

Layer	Tool	Description
Framework	Next.js 15.3	App Router + Server Actions
UI Layer	React 19	Concurrent rendering + Suspense support
Styling	Tailwind CSS + MUI	Utility layout + polished components
ORM	Prisma	Type-safe schema and DB access
Auth	Supabase Auth	Email & OAuth-based login
Database	Supabase (PostgreSQL)	Scalable cloud-native database
Deployment	Vercel	Instant deploys with preview environments
Language	TypeScript	Static typing throughout the stack

---

✅ Benefits of the Architecture

• Rapid startup with essential SaaS features included
• Seamless integration of backend + frontend logic
• Clean code organization for teams and scaling
• Built-in security via RLS and middleware
• Component-first design and mobile responsiveness
• Production-ready deployment workflow with Vercel

---

💡 Tips for Extending the Architecture

• Use lib/ for all reusable logic and client utilities.
• Create new features under /app/feature-name/.
• Add server logic under app/actions/ using Server Actions.
• Extend schema.prisma and re-sync your database with Prisma.
• Define RLS policies directly in Supabase for secure access control.