Project Structure

A well-organized project is easier to understand, maintain, and extend.

SaaSStinger Lite follows a layered architecture that separates routing, business logic, data access, and user interface components into dedicated directories. This keeps features modular and helps prevent application logic from becoming tightly coupled.

Rather than placing all logic inside pages or components, each layer has a clearly defined responsibility.

What You'll Learn

In this guide you'll learn:

• The overall repository structure
• The purpose of each top-level directory
• Where to add new code
• How data flows through the application
• Best practices for extending SaaSStinger Lite

Repository Structure

At a high level, the starter kit is organized like this:

src/
├── actions/
├── app/
├── components/
├── constants/
├── hooks/
├── lib/
├── providers/
├── server/
├── services/
├── shared/
└── types/

Each directory has a specific purpose.

app/

The app directory contains the application's routes and layouts using the Next.js App Router.

Examples include:

app/
├── auth/
├── dashboard/
├── invite/
└── onboarding/

This layer should focus on:

• Pages
• Layouts
• Route definitions
• Route composition

Avoid placing business logic directly inside route files.

actions/

The actions directory contains Server Actions that act as the entry point between the user interface and the application's business logic.

Examples include:

• Creating projects
• Updating profiles
• Managing workspaces
• Sending invitations
• Managing tasks

A Server Action should validate input, call the appropriate service, and return a result. It should not contain complex business rules.

components/

This directory contains reusable React components.

Components are grouped by feature.

Examples include:

components/
├── auth/
├── dashboard/
├── invites/
├── members/
├── notifications/
├── projects/
├── settings/
├── ui/
└── widgets/

The ui directory contains reusable interface primitives built with shadcn/ui.

Feature directories contain application-specific components.

hooks/

Custom React hooks live here.

Hooks encapsulate reusable client-side logic such as:

• Loading projects
• Fetching members
• Reading notifications
• Managing workspace state

Components should consume hooks rather than duplicating data-fetching logic.

services/

The service layer contains the application's business logic.

Examples include:

• Authentication
• Workspace management
• Team management
• Invitations
• Activity
• Metrics
• Subscriptions

Services answer the question:

How should the application behave?

They coordinate application rules without being concerned with routing or presentation.

server/

The server directory contains server-only code that should never execute in the browser.

This layer includes:

• Repositories
• Server utilities
• Database operations
• Domain-specific server logic

Repositories abstract Firestore access away from the rest of the application, making data access consistent and easier to maintain.

lib/

The lib directory contains shared infrastructure and utilities.

Examples include:

• Firebase initialization
• Authentication helpers
• Permissions
• RBAC utilities
• Firestore helpers
• Feature configuration
• Shared utility functions

Unlike services, code in lib is generally reusable infrastructure rather than business logic.

providers/

React Context providers are located here.

Examples include:

• Authentication
• Notifications
• Theme
• Workspace

Providers make shared application state available throughout the component tree.

shared/

This directory contains models and shared objects that are used across multiple layers of the application.

Keeping these definitions in a shared location helps avoid duplication.

types/

TypeScript interfaces and type definitions live here.

Examples include:

• Authentication types
• Billing types
• Invitation types
• Team types

Centralizing types improves consistency across the application.

How Data Flows

A typical request flows through the application like this:

User
   │
   ▼
Page
   │
   ▼
Server Action
   │
   ▼
Service
   │
   ▼
Repository
   │
   ▼
Cloud Firestore

Each layer has a single responsibility.

Where Should New Code Go?

Adding a New Page

Create a new route inside app/.

Adding Business Logic

Place application rules inside the appropriate service.

Reading or Writing Firestore

Use the repository layer rather than accessing Firestore directly from pages or components.

Creating UI

Place reusable interface elements inside components/.

Sharing Client Logic

Create a custom hook inside hooks/.

Adding Utilities

Place reusable helper functions inside lib/.

Best Practices

As you extend SaaSStinger Lite:

• Keep business logic out of components.
• Keep Firestore access inside repositories.
• Reuse services whenever possible.
• Build reusable UI components.
• Keep hooks focused on client-side concerns.
• Avoid duplicating logic across layers.

Following these principles keeps the project scalable as your application grows.

Common Mistakes

Putting Business Logic in Components

Components should focus on rendering UI, not implementing application rules.

Accessing Firestore Directly from Pages

Instead, use the repository and service layers.

This keeps data access centralized and easier to maintain.

Duplicating Logic

If multiple pages require the same behavior, move it into a shared service or utility.

Related Articles

• Authentication
• Workspaces
• RBAC
• Building Features
• Folder Reference

Next Steps

Now that you understand the project structure, continue with Your First Workspace to create and configure your first workspace in SaaSStinger Lite.