igniter-architecture

Igniter.js: Core Architecture

This document outlines the foundational architecture of an Igniter.js application when integrated with the Next.js App Router.

1. Core Architectural Principles

The application leverages the Next.js App Router to execute code on both the server (React Server Components, API Routes) and the client (Client Components). Igniter.js is integrated as a structured, type-safe API layer that sits within the Next.js project.

1.1. API Entry Point: The Bridge

All API requests are funneled through the main Express application, which acts as a bridge to the Igniter.js backend.

• File Location: src/index.ts
• Mechanism: This file uses the expressAdapter to integrate the Igniter.js router with Express. It translates incoming Express requests into a format Igniter.js can process and translates Igniter.js responses back into a format Express can serve. It handles all HTTP methods (GET, POST, etc.) for any route matching the IGNITER_API_BASE_PATH (e.g., /api/v1/*). You will rarely need to modify this file.

1.2. API Layer: Feature-Based Structure

All backend business logic is organized using a Feature-Based Architecture within the src/features directory.

• src/igniter.ts: The central configuration file where the igniter instance is created. This is where global plugins and adapters are registered.
• src/igniter.router.ts: This file assembles the main AppRouter by importing and registering all feature controllers. It serves as the single source of truth for your API's structure and endpoints.
• src/features/[feature]/controllers/: This is where your business logic resides. Each controller defines a set of related API actions (query, mutation).

1.3. The Universal Type-Safe Client

The file src/igniter.client.ts defines the isomorphic, type-safe Igniter.js API client. This is the primary interface for frontend-backend communication.

• Auto-Generated: This file MUST NOT be edited manually. It is a build artifact that is automatically regenerated by the development server whenever igniter.router.ts changes.
• Universal Operation: The client is designed to work seamlessly in all Next.js rendering environments:
  • React Server Components (RSC): You can call API actions directly as if they were local functions (e.g., await api.posts.list.query()). This executes a direct function call on the server, bypassing HTTP for maximum performance.
  • Client Components ('use client'): You must use the provided React Query hooks (e.g., api.posts.list.useQuery()). These hooks handle standard HTTP requests and manage the entire client-side state lifecycle, including loading, errors, and caching.