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

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() }));