vp-implement-module

Implement NestJS Module (VoxPopuli)

Overview

Pattern for creating a new NestJS module in VoxPopuli. Every module follows the same structure: injectable service, NestJS module with exports, Jest spec file, and wiring into AppModule.

When to Use

• Adding a new domain module to apps/api/src/
• Implementing a Linear epic that introduces a new service
• Not for: modifying existing modules, frontend work, or eval harness

Module Structure

apps/api/src/{module-name}/
  {module-name}.service.ts      # @Injectable() service
  {module-name}.module.ts       # NestJS module
  {module-name}.service.spec.ts # Jest tests
  {module-name}.controller.ts   # Only if HTTP endpoints needed

Implementation Checklist

1. Shared types first -- Add any new interfaces to libs/shared-types/src/lib/shared-types.ts and re-export from index.ts
2. Service -- @Injectable(), constructor injection for dependencies, JSDoc on public methods, strict TypeScript (no any)
3. Module -- Import dependencies, provide service, export service
4. Tests -- Jest with @swc/jest, use Test.createTestingModule(), mock all external dependencies (HTTP, LLM, cache)
5. Wire up -- Import module in apps/api/src/app/app.module.ts
6. Verify -- npx nx test api and npx nx build api

Key Conventions

Convention	Rule
DI	Constructor injection only, no direct imports between modules
External calls	All go through CacheService.getOrSet<T>()
LLM access	Via LlmService.getModel(), never instantiate providers directly
Token budgets	Via LlmService.getMaxContextTokens(), not hardcoded
SSE events	Only thought, action, observation, answer, error types
Test framework	Jest (not Vitest), mocks via jest.fn()

Common Mistakes

• Importing between NestJS modules directly instead of using DI
• Forgetting to export service from module (other modules can't inject it)
• Using ConfigModule import in module -- it's already global
• Hitting real APIs in tests -- always mock HTTP and LLM calls
• Using vi.fn() (Vitest) in API tests -- the API project uses Jest, use jest.fn()
• Not mocking LLM providers in test files that transitively import LlmService or AgentService -- Jest can't resolve @langchain/* ESM packages. Add these mocks at the top of spec files:

  jest.mock('../llm/providers/groq.provider', () => ({ GroqProvider: jest.fn() }));
  jest.mock('../llm/providers/claude.provider', () => ({ ClaudeProvider: jest.fn() }));
  jest.mock('../llm/providers/mistral.provider', () => ({ MistralProvider: jest.fn() }));