Controllers & Procedures

By the end of this guide, you'll understand how to create feature-scoped controllers, implement business logic through procedures, validate inputs with Zod schemas, and expose well-documented APIs through OpenAPI.

Before You Begin

Basic Knowledge: Familiarity with TypeScript, REST APIs, and basic Node.js concepts Prerequisites: Understanding of the Authentication & Sessions and Roles & Permissions concepts Environment: A running SaaS Boilerplate instance with database configured Optional: Experience with Zod for schema validation

Core Concepts

The SaaS Boilerplate uses Igniter as its API framework, providing a structured approach to building type-safe, well-documented APIs. Controllers and procedures work together to create a layered architecture that separates concerns while maintaining type safety throughout the application.

Controllers as Feature Boundaries

Controllers serve as the entry point for API endpoints within each feature. They are feature-scoped, meaning each business domain (leads, organizations, billing) has its own controller that groups related endpoints. Controllers handle:

• Request Routing: Mapping HTTP methods and paths to handler functions
• Input Validation: Using Zod schemas to validate and parse request data
• Authentication Guards: Enforcing role-based access control
• Response Formatting: Standardizing API responses
• Procedure Orchestration: Coordinating calls to business logic procedures

Procedures as Business Logic Layer

Procedures encapsulate the business logic and data access operations. They are injected into the Igniter context, making them available to controllers while maintaining clean separation of concerns. Procedures handle:

• Data Operations: CRUD operations on database entities
• Business Rules: Domain-specific validation and logic
• Side Effects: Notifications, integrations, and external service calls
• Data Transformation: Converting between database and API formats
• Error Handling: Business logic errors and edge cases

Schema-Driven Validation

Input validation is handled through Zod schemas that provide runtime type checking and automatic TypeScript inference. This ensures:

• Type Safety: Compile-time guarantees about data structures
• Runtime Validation: Automatic parsing and validation of request data
• Documentation: Schemas generate OpenAPI documentation automatically
• Developer Experience: IntelliSense and autocompletion in IDEs

OpenAPI Documentation

The framework automatically generates comprehensive OpenAPI documentation from your controllers and schemas. This provides:

• API Discovery: Interactive documentation for developers
• Type Generation: Client SDK generation for different languages
• Testing: Built-in API testing interfaces
• Contract Definition: Clear API contracts between frontend and backend

Data Models

The controller and procedure system defines several key interfaces and types that govern API structure and validation.

Schema and Documentation Generation

The CLI commands generate TypeScript schemas and OpenAPI documentation:

# Generate TypeScript schema for type safety
npx @igniter-js/cli generate schema

# Generate OpenAPI documentation
npx @igniter-js/cli generate docs

Troubleshooting

Best Practices