Architecture & Development | ShipSaaS Documentation

The boilerplate implements a strict 3-layer architecture that ensures separation of concerns, maintainability, and scalability. Each layer has specific responsibilities and communicates through well-defined interfaces.

Perfect for: Building maintainable, testable, and scalable SaaS applications with clear separation between UI, business logic, and data access.

Architecture Overview

The system follows a unidirectional data flow through three main layers:

3-Layer Architecture:

🖥️  PRESENTATION LAYER
├── React Server Components (RSC)
├── Client Components ("use client")
├── Server Actions (mutations)
└── DAL (Data Access Layer with cache)
                ⬇️
⚙️  SERVICE LAYER
├── Business Logic
├── Validation (Zod schemas)
├── Authorization (CASL RBAC)
├── Facades (interfaces)
└── Interceptors (logging, audit)
                ⬇️
🗄️  PERSISTENCE LAYER
├── Drizzle ORM
├── Database Models
├── Repositories (DAO pattern)
└── Type Transformations

Read Operations (Queries):

Component → DAL (with cache) → Facade → Service → Repository → Database

Write Operations (Mutations):

Server Action → Facade → Service (validation + auth) → Repository → Database

Key Benefits:

Cached reads with 'use cache' in the DAL function
Validated writes with business rules
Authorized access at service level
Clean separation of concerns

Core Architecture Principles

🏗️

Layered Architecture

Strict 3-layer separation

• Presentation: RSC, Client Components, Server Actions

• Service: Business logic, validation, authorization

• Persistence: Drizzle ORM, repositories, models

• No layer bypassing: Each layer calls only the next

🔄

Unidirectional Flow

Clear data movement

• Reads: Component → DAL → Service → Repository

• Writes: Server Action → Service → Repository

• Caching: DAL layer with 'use cache' + cacheTag

• Validation: Service layer with Zod schemas

🔐

Security & Authorization

RBAC with CASL

• Authorization: Every service operation checked

• Validation: Input validation at service boundary

• Type Safety: Domain types prevent data leaks

• Audit Trail: Interceptors log all operations

⚡

Performance

Optimized at every layer

• Server-first: RSC by default

• Caching: DAL layer, Partial Prerendering

• Database: Connection pooling with Drizzle

• Client: Minimal client-side JavaScript

Example: Complete Data Flow

Here's how a typical user operation flows through all layers:

Get User Profile:

typescript

// 🖥️ PRESENTATION (RSC Component)
import { getUserByIdDal } from '@/app/dal/user-dal'

export default async function UserProfile({ userId }: { userId: string }) {
  const user = await getUserByIdDal(userId) // Cached read
  return <div>{user.name}</div>
}

// 📊 DAL (Data Access Layer)
import { cache } from 'react'
import { cacheLife, cacheTag } from 'next/cache'
import { getUserByIdService } from '@/services/facades/user-service-facade'

// 'use cache' makes the read cacheable across requests; cache() from React
// still deduplicates it within a single request.
export const getUserByIdDal = cache(async (id: string) => {
  'use cache'
  cacheLife('hours')
  cacheTag(`user:${id}`)

  const userModel = await getUserByIdService(id)
  return transformToUserDTO(userModel) // Transform to domain type
})

// ⚙️ SERVICE (Business Logic)
export const getUserByIdService = async (id: string) => {
  const parsed = userUuidSchema.safeParse(id) // Validation
  if (!parsed.success) throw new ValidationError()

  const granted = await canReadUser(parsed.data) // Authorization
  if (!granted) throw new AuthorizationError()

  return await getUserByIdDao(parsed.data) // Call repository
}

// 🗄️ REPOSITORY (Data Access)
export async function getUserByIdDao(id: string): Promise<UserModel> {
  return await db.query.users.findFirst({
    where: eq(users.id, id)
  })
}

Update User Profile:

typescript

// 🖥️ PRESENTATION (Server Action)
import { updateUserService } from '@/services/facades/user-service-facade'

export async function updateUserAction(formData: FormData) {
  "use server"

  const result = await updateUserService({
    id: formData.get('id') as string,
    name: formData.get('name') as string,
    email: formData.get('email') as string
  })

  revalidatePath('/account')
  return result
}

// ⚙️ SERVICE (Business Logic)
export const updateUserService = async (data: UpdateUserInput) => {
  // 1. Validation
  const parsed = updateUserSchema.safeParse(data)
  if (!parsed.success) throw new ValidationError()

  // 2. Authorization
  const granted = await canUpdateUser(parsed.data.id)
  if (!granted) throw new AuthorizationError()

  // 3. Business Logic
  const updatedUser = await updateUserDao(parsed.data)

  // 4. Side Effects (optional)
  await sendUserUpdatedEmail(updatedUser)

  return updatedUser
}

// 🗄️ REPOSITORY (Data Access)
export async function updateUserDao(data: UpdateUserData) {
  return await db.update(users)
    .set({
      name: data.name,
      email: data.email,
      updatedAt: new Date()
    })
    .where(eq(users.id, data.id))
    .returning()
}

Key Benefits

✅

Maintainability

• Clear separation of concerns
• Easy to locate and fix issues
• Consistent patterns across features
• Self-documenting code structure

✅

Testability

• Each layer can be tested independently
• Easy mocking of dependencies
• Business logic isolated in services
• Database operations isolated in repositories

✅

Scalability

• Layers can scale independently
• Easy to add new features
• Caching at appropriate layers
• Performance optimizations per layer

Architecture Documentation

🖥️

Presentation Layer

RSC, Client Components, Server Actions, DAL, and Forms

⚙️

Service Layer

Business logic, validation, authorization, facades, and interceptors

🗄️

Persistence Layer

Drizzle ORM, models, repositories, and type transformations

🔧

Helpers Architecture

Client/server separation and utility organization

📁

Project Structure

File organization, naming conventions, and import rules

🧪

Development Workflow

Feature development process and testing strategies

Architecture ready! Your application follows enterprise-grade patterns that ensure maintainability, testability, and scalability as your SaaS grows.

Architecture Overview

The system follows a unidirectional data flow through three main layers:

3-Layer Architecture:

🖥️  PRESENTATION LAYER
├── React Server Components (RSC)
├── Client Components ("use client")
├── Server Actions (mutations)
└── DAL (Data Access Layer with cache)
                ⬇️
⚙️  SERVICE LAYER
├── Business Logic
├── Validation (Zod schemas)
├── Authorization (CASL RBAC)
├── Facades (interfaces)
└── Interceptors (logging, audit)
                ⬇️
🗄️  PERSISTENCE LAYER
├── Drizzle ORM
├── Database Models
├── Repositories (DAO pattern)
└── Type Transformations

Read Operations (Queries):

Component → DAL (with cache) → Facade → Service → Repository → Database

Write Operations (Mutations):

Server Action → Facade → Service (validation + auth) → Repository → Database

Key Benefits:

Cached reads with 'use cache' in the DAL function
Validated writes with business rules
Authorized access at service level
Clean separation of concerns

Core Architecture Principles

🏗️

Layered Architecture

Strict 3-layer separation

• Presentation: RSC, Client Components, Server Actions

• Service: Business logic, validation, authorization

• Persistence: Drizzle ORM, repositories, models

• No layer bypassing: Each layer calls only the next

🔄

Unidirectional Flow

Clear data movement

• Reads: Component → DAL → Service → Repository

• Writes: Server Action → Service → Repository

• Caching: DAL layer with 'use cache' + cacheTag

• Validation: Service layer with Zod schemas

🔐

Security & Authorization

RBAC with CASL

• Authorization: Every service operation checked

• Validation: Input validation at service boundary

• Type Safety: Domain types prevent data leaks

• Audit Trail: Interceptors log all operations

⚡

Performance

Optimized at every layer

• Server-first: RSC by default

• Caching: DAL layer, Partial Prerendering

• Database: Connection pooling with Drizzle

• Client: Minimal client-side JavaScript

Example: Complete Data Flow

Here's how a typical user operation flows through all layers:

Get User Profile:

typescript

// 🖥️ PRESENTATION (RSC Component)
import { getUserByIdDal } from '@/app/dal/user-dal'

export default async function UserProfile({ userId }: { userId: string }) {
  const user = await getUserByIdDal(userId) // Cached read
  return <div>{user.name}</div>
}

// 📊 DAL (Data Access Layer)
import { cache } from 'react'
import { cacheLife, cacheTag } from 'next/cache'
import { getUserByIdService } from '@/services/facades/user-service-facade'

// 'use cache' makes the read cacheable across requests; cache() from React
// still deduplicates it within a single request.
export const getUserByIdDal = cache(async (id: string) => {
  'use cache'
  cacheLife('hours')
  cacheTag(`user:${id}`)

  const userModel = await getUserByIdService(id)
  return transformToUserDTO(userModel) // Transform to domain type
})

// ⚙️ SERVICE (Business Logic)
export const getUserByIdService = async (id: string) => {
  const parsed = userUuidSchema.safeParse(id) // Validation
  if (!parsed.success) throw new ValidationError()

  const granted = await canReadUser(parsed.data) // Authorization
  if (!granted) throw new AuthorizationError()

  return await getUserByIdDao(parsed.data) // Call repository
}

// 🗄️ REPOSITORY (Data Access)
export async function getUserByIdDao(id: string): Promise<UserModel> {
  return await db.query.users.findFirst({
    where: eq(users.id, id)
  })
}

Update User Profile:

typescript

// 🖥️ PRESENTATION (Server Action)
import { updateUserService } from '@/services/facades/user-service-facade'

export async function updateUserAction(formData: FormData) {
  "use server"

  const result = await updateUserService({
    id: formData.get('id') as string,
    name: formData.get('name') as string,
    email: formData.get('email') as string
  })

  revalidatePath('/account')
  return result
}

// ⚙️ SERVICE (Business Logic)
export const updateUserService = async (data: UpdateUserInput) => {
  // 1. Validation
  const parsed = updateUserSchema.safeParse(data)
  if (!parsed.success) throw new ValidationError()

  // 2. Authorization
  const granted = await canUpdateUser(parsed.data.id)
  if (!granted) throw new AuthorizationError()

  // 3. Business Logic
  const updatedUser = await updateUserDao(parsed.data)

  // 4. Side Effects (optional)
  await sendUserUpdatedEmail(updatedUser)

  return updatedUser
}

// 🗄️ REPOSITORY (Data Access)
export async function updateUserDao(data: UpdateUserData) {
  return await db.update(users)
    .set({
      name: data.name,
      email: data.email,
      updatedAt: new Date()
    })
    .where(eq(users.id, data.id))
    .returning()
}

Key Benefits

✅

Maintainability

• Clear separation of concerns
• Easy to locate and fix issues
• Consistent patterns across features
• Self-documenting code structure

✅

Testability

• Each layer can be tested independently
• Easy mocking of dependencies
• Business logic isolated in services
• Database operations isolated in repositories

✅

Scalability

• Layers can scale independently
• Easy to add new features
• Caching at appropriate layers
• Performance optimizations per layer