Adaptive AI Tutoring Platform
The premise is that a tutor is only useful if it knows the actual material, so the platform ingests the learner's own documents, chunks and embeds them, and grounds every generated lesson in that corpus. Lesson generation is modelled as a state graph — plan, retrieve, draft, check — which means a long generation can be resumed after a failure instead of restarted, and each stage can be inspected when the output is wrong.
Monorepo: Fastify API, React client, and shared ai / db / shared packages
Documented as an architecture record. The design worth showing is the retrieval-grounded generation graph, not a hosted chat box.
From uploaded document to grounded lesson
Two pipelines share one datastore: ingestion turns documents into retrievable knowledge, and generation consumes it.
Upload, lesson view and exercises, with streamed output.
Turning a document into something the tutor can cite.
Highlights
Ingest, embed, retrieve, generate
The platform is a pipeline more than a chat app. Material goes in, becomes searchable, and then constrains what the model is allowed to assert. The AI package is deliberately isolated so the orchestration can be tested without a running server.
Web client
Upload, lesson browsing, exercises and the streaming lesson view.
- Consumes streamed generation over WebSockets.
- Shares types with the server through the shared package.
API server
Sessions, uploads, lesson endpoints and the WebSocket surface.
- Fastify with schema validation at the boundary.
- Holds no AI logic itself — it calls into the AI package.
AI package
The generation graph: planning, retrieval, drafting and checking.
- Modelled as an explicit state machine rather than a chain of prompts.
- Each node is independently testable and individually resumable.
Data layer
Relational records plus vector embeddings in one database, with Redis for coordination.
- Embeddings sit next to the rows they describe, so there is no sync problem.
- Redis holds generation locks and ephemeral session state.
Applications and workspace packages
A deliberately small surface: two applications over three shared packages. The AI package is isolated so the generation graph can be tested without a running server. 13 units across 4 groups.
Applications
2Workspace packages
3Generation stages
4Ingestion
4Stack by layer
Delivered work
Platform
- Fastify API with session handling, multipart upload and a WebSocket surface.
- React client with streamed lesson rendering.
- Shared type package keeping client and server structurally aligned.
AI pipeline
- Document ingestion for PDF and office formats with retrieval-sized chunking.
- Embedding and vector search inside the primary database.
- Four-stage generation graph with resumable state.
- Redis-backed locks to prevent duplicate concurrent generation.
Modules and demo strategy
Generation graph
Makes long generations debuggable and resumable.
- Explicit stages instead of one opaque prompt chain.
- A failure resumes from the last completed node.
Grounded retrieval
Ties lesson content to the learner's own material.
- Vector search co-located with relational data.
- Reduces confident-but-unsupported output.
Ingestion pipeline
Accepts real course material rather than clean text.
- PDF and office extraction with chunking tuned for retrieval.