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.

Innova Backend Serverless is the core REST API of the SuperProfe EdTech platform — a serverless NestJS application deployed on AWS Lambda and live at https://api.superprofes.app. It is purpose-built for Chilean primary school students in grades 3–6, orchestrating everything from student attempt ingestion and teacher worksheet processing to adaptive practice recommendation and mastery tracking.

​
What problem does it solve?

Traditional auto-grading answers a binary question: right or wrong. That is not enough for a teacher who needs to help a struggling student. Innova Backend Serverless classifies the specific procedural error a student made — for example, whether they forgot to carry a digit, misapplied a fraction rule, or confused percentage and ratio operations. Each attempt flows through a multi-layer classification pipeline that produces a structured errorTag drawn from a taxonomy of 2,600+ procedural errors aligned to the Chilean national curriculum. Teachers receive actionable alerts; students receive exercises calibrated to their individual mastery level rather than their age group.

​
Who is this for?

Developers integrating with the API

Backend and frontend engineers building the SuperProfe web app (Next.js), mobile practice app (Expo), or third-party integrations. You will consume the REST endpoints described in the API Overview and authenticate every request with a Supabase JWT.

Educators using SuperProfe

Teachers at Chilean primary schools who upload worksheets, review AI-generated solution keys, monitor student mastery dashboards, and act on the automated alerts this backend generates. Understanding the pipeline helps you interpret confidence scores and errorTag values in the UI.

Contributors and maintainers

Engineers working inside this repository — adding new rule-engine strategies, extending the Prisma schema, tuning BKT parameters, or deploying Lambda functions. Start with the Architecture page and the local setup steps in Quickstart.

​
How it works

Every student attempt passes through four classification layers in sequence. The first two run synchronously inside the Lambda response path; the remaining two run asynchronously in the background.

​
Layer 1 — Rule Engine (synchronous, <5 ms)

Based on Brown & VanLehn’s Repair Theory (1980), which established that procedural arithmetic errors are systematic and catalogable. The rule engine is implemented as one Strategy class per math topic wired by a Factory (topic.code → RuleStrategy). Deterministic subdomains — integer and fraction arithmetic, decimal operations, ratios, percentages, linear equations, powers, and roots — are classified here with no external calls. Target coverage is ≥75% of real attempts classified as something other than UNCLASSIFIED.

​
Layer 2 — BKT mastery update (synchronous, <1 ms)

Immediately after a classified attempt, the backend runs a closed-form Bayesian Knowledge Tracing update (Corbett & Anderson, 1995) to update pKnown for the (student, topic) pair: 
P(known | obs=1) = (1−pSlip)·pKnown / [(1−pSlip)·pKnown + pGuess·(1−pKnown)]
P(known | obs=0) =      pSlip·pKnown / [pSlip·pKnown + (1−pGuess)·(1−pKnown)]
P(Ln)            = P(known | obs) + (1 − P(known | obs))·pTransit
Default parameters: pL0=0.30, pT=0.10, pS=0.10, pG=0.20. Nightly recalibration by innova-ai-engine writes updated parameters back to Postgres.

​
Layer 3 — IRT adaptive practice (nightly batch)

The next exercise for each student is chosen by maximising Fisher information a²·P(θ)·(1−P(θ)) at the student’s current ability estimate θ (Lord, 1980 IRT 2PL model). Calibration runs overnight in the innova-ai-engine Python service and stores updated item and student parameters in Postgres.

​
Layer 4 — LLM async classification

Attempts that the rule engine cannot classify are tagged UNCLASSIFIED and pushed to the llm-classify-queue SQS queue. The innova-ai-engine LLM classifier worker picks them up and classifies them via Anthropic Claude (Haiku/Sonnet) against the full proprietary error taxonomy, using prompt caching and forced structured output. The resolved errorTag is written back to Postgres asynchronously.

​
Tech stack

TechnologyVersionRole
NestJS11HTTP framework — DI, Guards, Interceptors
TypeScript5 (strict)noImplicitAny, strictNullChecks, exactOptionalPropertyTypes
Prisma7ORM — versioned migrations, generated types, serverless-safe adapter
Supabase—Auth (JWKS RS256 JWT) + managed Postgres
MongoDB Atlas—Schema-less raw telemetry storage
AWS Lambda + SQS + S3—Pay-per-request compute, durable messaging, object storage
Serverless Framework3One-command deploy of six Lambda functions + SQS/S3 resources

​
Explore further

Quickstart

Clone the repo, spin up local infra with Docker Compose, and submit your first student attempt in under ten minutes.

Architecture

Full system diagram: API layer, six Lambda functions, SQS queues, dual-database storage, and AI engine integration.

Rule Engine

Deep dive into the Strategy + Factory pattern, per-topic strategies, and how new error types are added to the rule engine.

API Overview

All REST endpoints, authentication requirements, request/response shapes, and error codes.
The full, always-current OpenAPI specification (generated at boot from @nestjs/swagger decorators) is available at /docs on any running server instance — for example http://localhost:3000/docs in local development or https://api.superprofes.app/docs in production. The raw JSON is served at /docs/openapi.json.

Build docs developers (and LLMs) love

Get started for freeTalk to us