Folder Structure & Conventions - vm5lab/SaaSKit GitHub Wiki

🗂 Folder Structure & Conventions

SaaSKit follows a clean, modular directory structure that enables clarity, scalability, and maintainability in SaaS development. Each folder is designed with a clear responsibility in mind, making onboarding and contribution straightforward for teams.

🌳 Root Structure

/
├── app/                 # App Router pages and logic (Next.js 15.3)
├── components/          # UI & layout components
├── lib/                 # Utility libraries and clients (auth, prisma, supabase)
├── prisma/              # Prisma schema & migrations
├── public/              # Static assets (images, icons, etc.)
├── styles/              # Global Tailwind & MUI styles (if needed)
├── .env.local           # Local environment variables
├── tsconfig.json        # TypeScript configuration
└── next.config.js       # Next.js configuration

📁 app/ – App Router Pages

All application pages and routes live under this folder. Each subfolder maps to a URL path.

app/
├── layout.tsx            # Shared layout wrapper (Topbar + Sidebar)
├── page.tsx              # Home or landing page
├── dashboard/            # User dashboard
├── auth/login/           # Auth pages (login, register)
├── settings/             # Profile or preferences
├── admin/                # Admin-only sections
├── actions/              # Server Actions (backend logic)

✅ Best Practices

  • Keep feature pages in separate folders for scalability.
  • Use Server Actions for backend logic inside app/actions/.

📁 components/ – UI Components

Contains all reusable and layout components.

components/
├── layout/              # Topbar, Sidebar, LayoutShell
├── ui/                  # Generic UI components (Button, Card, Form, Table)

✅ Best Practices

  • Prefix internal components with lowercase.
  • Keep components atomic and composable.
  • Tailor MUI + Tailwind components for consistency.

📁 lib/ – Utilities & Clients

Houses all shared helpers, third-party clients, and utility functions.

lib/
├── prisma.ts            # Prisma Client instance
├── supabase.ts          # Supabase Client
├── auth.ts              # Get current user, role-checking, session logic

📁 prisma/ – Prisma Schema

Handles all data modeling with schema.prisma and migration configurations.

prisma/
├── schema.prisma        # Defines DB models (User, Role, Project, etc.)

📁 public/ – Static Assets

Place all public-accessible files here such as images, favicons, logos.

🔧 Environment Configuration

Environment variables should be placed in:

  • .env.local (development)
  • .env.production (production)

Common Keys

SUPABASE_URL=
SUPABASE_ANON_KEY=
NEXT_PUBLIC_SITE_URL=

📌 Naming Conventions

Item Convention Example
Files kebab-case or lowercase layout.tsx, auth.ts
Folders kebab-case app/dashboard
Components PascalCase Sidebar.tsx
Server Action camelCase createProject.ts
Prisma Model PascalCase User, Project

✅ Summary

  • Organize by responsibility (app, components, lib, prisma).
  • Use clear, consistent naming to avoid confusion.
  • Encapsulate business logic using Server Actions.
  • Keep your schema.prisma in sync with Supabase.

Next: Read more about Server Actions & Data Flow.