Folder Structure

SaaSStinger Lite uses a layered Next.js application structure designed for building and extending SaaS applications.

The application separates:

• UI components
• Routing
• Server actions
• Business logic
• Data access
• Shared types

This keeps features easier to maintain as the application grows.

Application Structure

The main application code lives inside:

src/

Structure:

src/

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

App Router

Location:

src/app/

Contains Next.js routes, pages, layouts, and API routes.

Examples:

src/app/

├── auth/
├── dashboard/
├── invite/
├── onboarding/
├── marketing/
└── api/

Responsibilities:

• Page routing
• Layouts
• Route handlers
• Application entry points

Dashboard Routes

Location:

src/app/dashboard/

Contains authenticated application pages.

Examples:

dashboard/

├── activity/
├── invites/
├── members/
├── projects/
├── settings/
└── usage/

These routes provide the main SaaS application experience.

Components

Location:

src/components/

Contains reusable React components.

Structure:

components/

├── auth/
├── dashboard/
├── invites/
├── members/
├── projects/
├── settings/
└── ui/

UI Components

Location:

src/components/ui/

Contains reusable interface primitives.

Examples:

button.tsx
dialog.tsx
card.tsx
table.tsx
input.tsx

These components are built using shadcn/ui patterns.

Feature Components

Feature-specific components are grouped by domain.

Examples:

components/projects/

ProjectCard.tsx

ProjectDialog.tsx

ProjectList.tsx

Feature components should remain close to the feature they support.

Server Actions

Location:

src/actions/

Contains server actions used by the application.

Examples:

actions/

workspace.ts

invites.ts

projects.ts

members.ts

Responsibilities:

• Receive requests from UI
• Validate input
• Call server-side logic
• Return results

Services

Location:

src/services/

Contains application business logic.

Examples:

services/

├── auth/
├── workspace/
├── invite/
├── profile/
└── team/

Services handle operations such as:

• Creating workspaces
• Managing invitations
• Updating profiles

Server Layer

Location:

src/server/

Contains server-only application logic.

Examples:

server/

├── repositories/
├── workspace.server.ts
├── project.server.ts
├── invite.server.ts
└── audit.server.ts

This layer interacts with:

• Firebase Admin SDK
• Repositories
• Server-side operations

Repository Layer

Location:

src/server/repositories/

Handles database access.

Examples:

repositories/

workspace.repository.ts

project.repository.ts

membership.repository.ts

Responsibilities:

• Firestore queries
• Data retrieval
• Data persistence

Data Flow

The general application flow:

Component

    ↓

Server Action

    ↓

Service

    ↓

Repository

    ↓

Firestore

Each layer has a specific responsibility.

Hooks

Location:

src/hooks/

Contains reusable client-side React hooks.

Examples:

useMembers.ts

useWorkspace.ts

useProjects.ts

Hooks handle:

• Client state
• Data loading
• UI interactions

Providers

Location:

src/providers/

Contains React context providers.

Examples:

AuthProvider.tsx

WorkspaceProvider.tsx

ThemeProvider.tsx

Providers supply application-wide state.

Libraries

Location:

src/lib/

Contains shared utilities and configurations.

Examples:

lib/

├── firebase/
├── auth/
├── permissions.ts
├── rbac.ts
└── utils.ts

Common responsibilities:

• Firebase initialization
• Authentication helpers
• Permission utilities
• Shared functions

Shared Types

Location:

src/shared/

Contains types shared across application layers.

Examples:

project.ts

task.ts

activity.ts

Type Definitions

Location:

src/types/

Contains TypeScript types.

Examples:

types/

auth.ts

invite.ts

team.ts

Used for:

• Type safety
• API contracts
• Data models

Files Developers Usually Modify

Developers commonly extend:

src/components/

src/actions/

src/services/

src/server/

src/hooks/

src/types/

These are the main extension points.

Files and Folders to Avoid Editing

node_modules

node_modules/

Generated dependency files.

Never modify manually.

Build Output

.next/

Generated by Next.js.

Emulator Data

Example:

emulator-data/

Generated local Firebase data.

Logs

Examples:

firebase-debug.log

firestore-debug.log

Generated debugging files.

Adding a New Feature

A typical feature may require:

Component

      ↓

Hook

      ↓

Server Action

      ↓

Service

      ↓

Repository

      ↓

Firestore

Depending on complexity, not every layer is required.

Best Practices

• Keep UI logic inside components.
• Keep business logic inside services.
• Keep database access inside repositories.
• Reuse shared types.
• Avoid placing business rules directly inside pages.

Related Articles

• Repository Pattern
• Working With Services
• Creating Server Actions
• Adding Features
• Firestore Schema

Next Steps

Continue with Configuration Reference to understand important application configuration files.