SaaSKit Project Structure - vm5lab/SaaSKit GitHub Wiki
SaaSKit Detailed Project Structure
Overview
The SaaSKit project structure follows a feature-based organization pattern within the Next.js 15.3 App Router architecture. This structure is designed to support modularity, maintainability, and scalability as your SaaS application grows. The organization emphasizes separation of concerns while keeping related code logically grouped.
Root Directory
/
├── .github/ # GitHub configuration
├── .vscode/ # VS Code settings
├── app/ # Next.js App Router
├── components/ # Reusable UI components
├── config/ # Application configuration
├── lib/ # Utility functions and services
├── prisma/ # Database schema and migrations
├── public/ # Static assets
├── styles/ # Global styles
├── types/ # TypeScript type definitions
├── middleware.ts # Next.js middleware for auth
├── next.config.js # Next.js configuration
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── tailwind.config.js # Tailwind CSS configuration
└── .env.example # Example environment variables
App Directory (Next.js App Router)
/app/
├── layout.tsx # Root layout (includes Sidebar + Topbar)
├── page.tsx # Landing page
├── favicon.ico # Site favicon
├── actions/ # Server Actions
│ ├── auth/ # Authentication actions
│ ├── user/ # User management actions
│ ├── tenant/ # Tenant management actions
│ ├── billing/ # Subscription and billing actions
│ └── admin/ # Admin-specific actions
├── api/ # API routes (when needed)
│ ├── webhooks/ # External service webhooks
│ └── internal/ # Internal API endpoints
├── (auth)/ # Auth routes (grouped)
│ ├── login/ # Login page
│ │ └── page.tsx
│ ├── register/ # Registration page
│ │ └── page.tsx
│ ├── forgot-password/ # Password recovery
│ │ └── page.tsx
│ └── layout.tsx # Auth-specific layout
├── (dashboard)/ # Dashboard routes (grouped)
│ ├── dashboard/ # Main dashboard
│ │ ├── page.tsx
│ │ └── loading.tsx # Loading state
│ ├── projects/ # Projects feature
│ │ ├── page.tsx # Projects list
│ │ ├── [id]/ # Specific project
│ │ │ ├── page.tsx
│ │ │ ├── settings/
│ │ │ │ └── page.tsx
│ │ │ └── members/
│ │ │ └── page.tsx
│ │ └── create/
│ │ └── page.tsx
│ ├── settings/ # User & account settings
│ │ ├── page.tsx # Settings overview
│ │ ├── profile/ # Profile settings
│ │ │ └── page.tsx
│ │ ├── billing/ # Billing settings
│ │ │ └── page.tsx
│ │ ├── team/ # Team management
│ │ │ └── page.tsx
│ │ └── notifications/ # Notification preferences
│ │ └── page.tsx
│ └── layout.tsx # Dashboard layout
└── (admin)/ # Admin section (grouped)
├── admin/ # Admin dashboard
│ ├── page.tsx
│ ├── users/ # User management
│ │ ├── page.tsx
│ │ └── [id]/
│ │ └── page.tsx
│ ├── tenants/ # Tenant management
│ │ ├── page.tsx
│ │ └── [id]/
│ │ └── page.tsx
│ └── settings/ # Admin settings
│ └── page.tsx
└── layout.tsx # Admin-specific layout
Components Directory
/components/
├── layout/ # Layout components
│ ├── Sidebar.tsx # Main navigation sidebar
│ ├── Topbar.tsx # Top navigation bar
│ ├── Footer.tsx # Page footer
│ └── PageHeader.tsx # Consistent page headers
├── ui/ # UI components (shareable)
│ ├── Button/ # Button components
│ │ ├── Button.tsx
│ │ ├── IconButton.tsx
│ │ └── index.ts
│ ├── Card/ # Card components
│ │ ├── Card.tsx
│ │ ├── CardHeader.tsx
│ │ ├── CardBody.tsx
│ │ ├── CardFooter.tsx
│ │ └── index.ts
│ ├── Form/ # Form components
│ │ ├── Input.tsx
│ │ ├── Select.tsx
│ │ ├── Checkbox.tsx
│ │ ├── RadioGroup.tsx
│ │ ├── Switch.tsx
│ │ ├── TextArea.tsx
│ │ └── index.ts
│ ├── Feedback/ # Feedback components
│ │ ├── Alert.tsx
│ │ ├── Toast.tsx
│ │ ├── Modal.tsx
│ │ ├── Spinner.tsx
│ │ └── index.ts
│ ├── Data/ # Data display components
│ │ ├── Table.tsx
│ │ ├── Pagination.tsx
│ │ ├── Badge.tsx
│ │ ├── Avatar.tsx
│ │ └── index.ts
│ └── Navigation/ # Navigation components
│ ├── Tabs.tsx
│ ├── Breadcrumbs.tsx
│ ├── Dropdown.tsx
│ └── index.ts
├── auth/ # Auth-specific components
│ ├── LoginForm.tsx
│ ├── RegisterForm.tsx
│ ├── ForgotPasswordForm.tsx
│ └── OAuthButtons.tsx
├── dashboard/ # Dashboard components
│ ├── DashboardStats.tsx
│ ├── ActivityFeed.tsx
│ ├── WelcomeCard.tsx
│ └── NotificationsList.tsx
├── settings/ # Settings components
│ ├── ProfileForm.tsx
│ ├── BillingForm.tsx
│ ├── TeamTable.tsx
│ └── NotificationSettings.tsx
├── admin/ # Admin components
│ ├── UserTable.tsx
│ ├── TenantTable.tsx
│ ├── AuditLogTable.tsx
│ └── SystemStats.tsx
└── features/ # Feature-specific components
├── projects/ # Project components
├── billing/ # Billing components
├── teams/ # Team components
└── notifications/ # Notification components
Lib Directory
/lib/
├── prisma.ts # Prisma client setup
├── supabase.ts # Supabase client setup
├── auth/ # Authentication utilities
│ ├── session.ts # Session management
│ ├── permissions.ts # Permission helpers
│ └── roles.ts # Role definitions
├── api/ # API utilities
│ ├── fetcher.ts # API fetching wrapper
│ ├── errorHandler.ts # API error handling
│ └── responseParser.ts # Response parsing
├── hooks/ # Custom React hooks
│ ├── useAuth.ts # Authentication hook
│ ├── useForm.ts # Form handling hook
│ ├── useToast.ts # Toast notification hook
│ └── useMediaQuery.ts # Responsive design hook
├── utils/ # Utility functions
│ ├── formatting.ts # Text/date formatting
│ ├── validation.ts # Input validation
│ ├── calculations.ts # Business calculations
│ └── helpers.ts # General helpers
├── services/ # Service integrations
│ ├── email.ts # Email service
│ ├── payments.ts # Payment processing
│ ├── storage.ts # File storage
│ └── analytics.ts # Analytics integration
├── context/ # React context providers
│ ├── AuthContext.tsx # Authentication context
│ ├── ThemeContext.tsx # Theme/appearance context
│ └── ToastContext.tsx # Notification context
└── constants/ # Application constants
├── routes.ts # Route definitions
├── plans.ts # Subscription plan details
├── permissions.ts # Permission constants
└── config.ts # Misc configuration values
Prisma Directory
/prisma/
├── schema.prisma # Database schema
├── migrations/ # Database migrations
└── seed.ts # Seed data for development
Types Directory
/types/
├── index.ts # Type exports
├── auth.ts # Authentication types
├── user.ts # User-related types
├── tenant.ts # Tenant-related types
├── billing.ts # Subscription and billing types
├── api.ts # API request/response types
└── common.ts # Common utility types
Config Directory
/config/
├── site.ts # Site-wide configuration
├── features.ts # Feature flags
├── navigation.ts # Navigation structure
├── theme.ts # Theme configuration
└── integrations.ts # Third-party integration configs
Public Directory
/public/
├── images/ # Static images
│ ├── logo.svg # Site logo
│ ├── favicon/ # Favicon files
│ ├── icons/ # Icon assets
│ └── illustrations/ # Illustration assets
├── fonts/ # Custom fonts
└── locales/ # i18n translation files
Styles Directory
/styles/
├── globals.css # Global CSS
└── themes/ # Theme-specific styles
├── light.css # Light theme
└── dark.css # Dark theme
Key Development Files
/.env.example # Example environment variables
# Example .env.example contents
# Core
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/saaskit"
# Authentication
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key
# Payments (Stripe)
STRIPE_API_KEY=your-stripe-api-key
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=your-stripe-public-key
# Email (SendGrid, Postmark, etc.)
EMAIL_API_KEY=your-email-api-key
[email protected]
Implementation Best Practices
App Directory
- Group related routes using parentheses notation
(groupname)for logical organization without affecting URL structure - Leverage Next.js features like loading states, error boundaries, and metadata API
- Keep page components focused on layout and composition of other components
- Use Server Components for data fetching and rendering where possible
Components Directory
- Follow a component-first design approach
- Create higher-level components from UI primitives
- Maintain consistent props and behavior patterns
- Document components with JSDoc or Storybook
Lib Directory
- Keep utility functions pure and testable
- Centralize external service integrations
- Use dependency injection patterns where suitable
- Document complex business logic
Prisma Schema
- Define clear relationships between models
- Use appropriate field types and constraints
- Add meaningful comments to models
- Create database indexes for performance
Server Actions
- Place related actions in feature-specific folders
- Implement proper error handling and validation
- Add logging for debugging and monitoring
- Apply appropriate authorization checks
Conclusion
This project structure is designed to support the development of complex SaaS applications while maintaining code organization, promoting reusability, and facilitating team collaboration. The structure scales well as new features are added and provides clear separation of concerns while keeping related code together.
The organization follows modern Next.js patterns and best practices, with emphasis on Server Components, React Server Actions, and strong typing throughout the application. It's built to support the multi-tenant, scalable nature of SaaS applications while providing a solid foundation for rapid development.