Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vruizz22/innova-backend-serverless/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through spinning up the full Innova Backend Serverless stack on your local machine. The local environment mirrors production as closely as possible: NestJS runs in watch mode, MongoDB and LocalStack (SQS + S3 emulation) run in Docker, and Prisma manages schema migrations against a Supabase-hosted or local Postgres database.

​
Prerequisites

Before you begin, make sure the following tools are available on your machine:
  • Node.js ≥ 20 — install via nvm to keep versions isolated across projects
  • pnpm ≥ 9 — enable with corepack enable && corepack prepare pnpm@latest --activate
  • Docker + Docker Compose v2 — required for MongoDB and LocalStack containers
  • Supabase project or local Postgres — the relational database and auth layer; a free Supabase project covers both

​
Setup Steps

1

Clone the repository and install dependencies

git clone https://github.com/vruizz22/innova-backend-serverless.git
cd innova-backend-serverless
pnpm install
2

Configure your environment

Copy the example file and fill in the required values. At minimum you need DATABASE_URL, MONGODB_URI, and your Supabase keys. SQS queue URLs can be pointed at LocalStack for fully local development (see the Environment Variables reference for LocalStack URL format).
cp .env.example .env
# Open .env and fill in:
#   DATABASE_URL, MONGODB_URI
#   SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
#   SQS_* queue URLs (LocalStack or real AWS)
3

Start local infrastructure

This single command launches MongoDB 7 (telemetry store) and LocalStack 3 (SQS + S3 emulation). Both containers persist data in named Docker volumes so they survive restarts.
docker compose up -d
Confirm both containers are healthy:
docker compose ps
4

Apply database migrations

Run all pending Prisma migrations against the database pointed to by DATABASE_URL. On first run this creates the full v9 schema.
pnpm prisma migrate dev
5

Seed demo data

Populate the database with a demo school, courses, students, and exercises so you have realistic data to work with immediately.
pnpm prisma db seed
6

(Optional) Seed demo auth users

Create the corresponding Supabase Auth identities for the seeded demo users. This step is guarded by two environment flags to prevent accidental execution.
ALLOW_SEED=1 SEED_DEMO_PASSWORD=secret pnpm seed:auth
The script calls the Supabase Admin REST API and is fully idempotent — running it twice is safe.
7

Start the development server

NestJS starts in watch mode with hot reload. The server listens on port 3000 by default.
pnpm start:dev
You should see Pino JSON logs and a line confirming the application is listening on http://localhost:3000.
8

Verify the installation

Check the health endpoint and browse the auto-generated OpenAPI docs:
curl http://localhost:3000/health
# Expected: 200 OK
Then open your browser at http://localhost:3000/docs to explore the full Swagger UI.

​
Docker Compose Services

The docker-compose.yml in the repository root provides two services. Postgres is intentionally not included — it is provided by your Supabase project or a local Postgres instance that you configure via DATABASE_URL.
ServicePortDescription
mongodb27017MongoDB 7 used as the telemetry store for raw attempt events and AI job audit records
localstack4566LocalStack 3 emulating AWS SQS and S3, enabling the full async pipeline without a real AWS account
The .env.example file shows DATABASE_URL pointing to a local Postgres on port :5433 (postgresql://postgres:innova_secret@localhost:5433/innova_dev_db). If you are using a Supabase project instead, replace this with your project’s connection string — the session pooler URL (port :5432) is fine for local migration work.

​
Local SQS Consumer

The OCR → attempts reprocess loop requires an active consumer to drain the attempt-reprocess queue. In production this is a Lambda function triggered by SQS events. Locally, run the consumer script in a separate terminal: 
pnpm consume:reprocess
This script (scripts/local-reprocess-consumer.ts) polls the LocalStack SQS queue in a tight loop and processes each message the same way the Lambda worker does in production.

​
Common Commands

Run pnpm prisma studio at any time to open a browser-based GUI at http://localhost:5555 where you can inspect, filter, and edit every table in the Postgres database without writing a SQL query.
CommandDescription
pnpm start:devStart the NestJS server with hot-reload (TypeScript watch mode)
pnpm start:prodStart the compiled server from dist/main (production binary)
pnpm buildCompile the project with nest build for production bundling
pnpm lintRun ESLint with auto-fix across all source and test files
pnpm formatRun Prettier across all src/**/*.ts and test/**/*.ts files
pnpm testRun all Jest unit tests
pnpm test:watchRun Jest in interactive watch mode
pnpm test:covRun tests and generate a coverage report (CI gate: ≥ 75%)
pnpm test:e2eRun end-to-end tests (requires a test database; see test/jest-e2e.json)
pnpm prisma studioOpen the Prisma database GUI in your browser
pnpm prisma migrate dev --name <name>Create and apply a new named Prisma migration
pnpm consume:reprocessRun the local SQS consumer for the attempt-reprocess queue
pnpm seed:authSeed Supabase Auth demo users (requires ALLOW_SEED=1 and SEED_DEMO_PASSWORD)
docker compose logs -fStream live logs from the MongoDB and LocalStack containers
docker compose down -vStop all containers and delete named volumes (wipes local data)

Build docs developers (and LLMs) love

Get started for freeTalk to us