NestJS Server Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• apps/server/src/main.ts
• apps/server/package.json
• AGENTS.md
• README.md
• apps/server/nest-cli.json

The NestJS server acts as the control plane for the Opificia software factory, providing the API and worker infrastructure required to manage AI agents. It orchestrates the lifecycle of turning tickets into pull requests by managing sandboxes, worker tasks, and GitHub integrations.

The server is built using TypeScript on Node.js 24 and leverages the NestJS framework. It supports multiple operational roles, allowing it to function as a standalone API server, a background worker, or a combined instance.

Sources: apps/server/package.json:1-10, AGENTS.md:7-15, apps/server/src/main.ts:16-20

Architecture and Operational Roles

The server initialization logic determines its behavior based on the OPIFICIA_ROLE configuration. This allows for horizontal scaling by separating the API traffic from background task processing.

Role Transitions

The following diagram illustrates how the server initializes services based on its assigned role.

The server checks the OPIFICIA_ROLE environment variable during the bootstrap phase to enable specific modules.

Sources: apps/server/src/main.ts:31-51

Service Components

The server integrates several core services to handle the agentic workflow:

Component	Description	Source
DockerService	Manages agent sandboxes and ensures the sandbox image exists.	main.ts:32
SandboxGateway	Provides communication infrastructure for agent sandboxes.	main.ts:36
SessionsService	Reconciles active agent sessions.	main.ts:37
OutboxWorker	Processes background tasks and events.	main.ts:38
PollerService	Monitors GitHub for new issues and changes.	main.ts:39

Request Pipeline and Middleware

The server configures a specific global request pipeline to handle authentication and data parsing. It uses better-auth for identity management, which requires specific placement before standard body parsers.

Authentication handlers are mounted before JSON parsing because better-auth needs to read the raw request body.

Sources: apps/server/src/main.ts:25-30

Global Configuration Constants

The server applies these settings globally during initialization:

• Global Prefix: All routes are prefixed with /api.
• Body Limit: JSON payloads are restricted to a maximum of 1mb.
• Global Filters: A DomainErrorFilter handles exceptions across all controllers.
• Network Interface: The API listens on 127.0.0.1.

Sources: apps/server/src/main.ts:28-30, apps/server/src/main.ts:48

Project Structure and Build

The server is a package within a pnpm workspace. It depends on shared contracts and several infrastructure drivers.

Dependencies

Key dependencies include:

• @opificia/contracts: Shared TypeScript types and interfaces.
• prisma: Database ORM for PostgreSQL.
• dockerode: Interface for Docker sandbox management.
• iovalkey: Client for Valkey (Redis-compatible) storage.
• better-auth: Authentication framework.

Sources: apps/server/package.json:20-35

Build Configuration

The build process uses the Nest CLI and includes Prisma client generation.

{
  "compilerOptions": {
    "deleteOutDir": true
  }
}

Sources: apps/server/nest-cli.json:1-7, apps/server/package.json:7-13

Conclusion

NestJS Server Configuration provides a flexible, role-based infrastructure for the Opificia control plane. By separating API and worker concerns and strictly managing the request pipeline for authentication and sandboxing, the server supports the project's goals of self-hostability and sovereign control over AI agent environments.