Guides

Practical guides for working with Archipel packages in your NestJS application.

Foundations

Guide	What you'll learn
Getting Started	Install packages, register your first module, implement ports, and run the app.
Migrating to v1	Move a consuming NestJS 12 application to Archipel's ESM-only package contract.
Configuration Management	Type-safe config keys, strategy-based resolution, central registry, and validation.
Application Bootstrap	Compose NestJS startup with platform-bootstrap, Express middleware, security, sessions, and OpenAPI.
Composition Context	Stage-aware, configuration-driven module composition without direct process.env access.
Implementing Ports	How the port/adapter pattern works, how to write adapters, and how to test them.
Controller Best Practices	Structure controllers with Standard Schema, ResponseReturn2, guards, DI, and the @Api decorator.
Request & Response Models	Standard Schema contracts and the decorated class DTO migration fallback.
Testing	Unit testing services, testing port adapters, integration testing with real databases.
TSDoc Guidelines	Documentation standards for public APIs and generated reference pages.

Security & Identity

Guide	What you'll learn
Authentication & Authorization	JWT tokens, role-based access, custom scopes, MFA, sessions, and OAuth social login.
Cryptography & OTP	Bcrypt password hashing, prefixed UUIDs, and TOTP multi-factor authentication.

Data & Storage

Guide	What you'll learn
Database Setup	PostgreSQL via Prisma, Accelerate, repositories, queries, transactions, and health.
Blob Storage	Multi-provider file storage, uploads, signed URLs, and metadata tracking.
Document Generation	Generate PDF and DOCX from templates with variable substitution and image processing.
E-Signing Integration	Electronic signature workflows, provider setup, and webhook handling.

Communication & Payments

Guide	What you'll learn
Email Delivery	Multi-provider email sending, template engines, and verification flows.
Email Templates	Create, register, and override email templates with ResourceManager.
Payments & Feature Gating	Payment provider integration, webhook handling, and feature-based access control.

Operations & Observability

Guide	What you'll learn
Feature Flags	Toggle features at runtime with Azure App Configuration or Vercel Edge Config.
Telemetry & Observability	OpenTelemetry metrics, distributed tracing, and structured logging.
Analytics & Error Tracking	Capture errors and user context with Sentry, AppInsights, or Datadog.
Caching	In-memory LRU and Redis layered caches with TTL, stale-while-revalidate, and metrics.
Queue Infrastructure	In-memory FIFO, BullMQ (Redis), and Azure Service Bus job queues.
Health Indicators	Integrate health checks from all platform libraries using the unified health architecture.

AI & Extensibility

Guide	What you'll learn
Intelligence Prompts Warm-up	Define, bind, execute, validate, and test reusable text and structured prompts.
AI Language Generation	Provider-neutral text, structured output, streaming, tools, agents, and per-request model policy.
AI Image Generation	Provider-neutral image generation with tree-shakable provider model loaders.
AI Realtime Voice	Server-owned live audio/text sessions, interaction modes, durable streaming, metering, and explicit recovery.
MCP Server	Build MCP servers with tools, resources, and prompts for AI agent integration.

Platform Internals

Guide	What you'll learn
OpenAPI & Feature Discovery	Multi-document Swagger UI, the @Api decorator, and automatic per-module doc discovery.
Resource Management	Load templates, assets, and files from disk, blob storage, or memory via ResourceManager.