Skip to content

Backend Development Guide

Purpose

This guide defines the expected workflow for building backend features and endpoints in a consistent, review-friendly way using our modern stack.

Workflow (Red-Green-Refactor)

  1. Sync: Pull latest from dev and create a feature branch.
  2. Service: Identify the owner (NestJS Core or FastAPI Solver).
  3. Red: Write a failing unit/integration test in Jest or pytest.
  4. Green: Implement the logic. Use PGLite for ephemeral DB tests.
  5. Refactor: Clean up the code while keeping tests green.
  6. Swagger: Update or create the required API definitions.
  7. PR: Open a PR into dev once local checks pass.

Backend Technology Stack

Component Technology Role
API Framework NestJS Main core API & business logic
Data Access DrizzleORM Typesafe DB modeling & migrations
Job Queue BullMQ Async jobs (PDF Parsing, Solver triggers)
Solver API FastAPI High-performance Python bridge
Auth OAuth 2.0 Session management & Google OAuth2

Definition of Done

Backend Checklist
  • [ ] Work is isolated in a feature branch.
  • [ ] Swagger definitions are complete and tested.
  • [ ] Unit and Integration tests are passed.
  • [ ] Drizzle migrations are generated and tested.
  • [ ] CI passes successfully.
  • [ ] Code follows the Core-and-Adapter pattern.

Database Strategy

Use Drizzle for all core entity management. Ensure schemas are located in packages/database/schema.

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: text('email').unique().notNull(),
});

Use PGLite for lightning-fast, isolated unit tests. No Docker required.

pnpm run test:pglite