How relichtyy/navigator works
1. Repository shape
- The real application lives in syllabus-navigator/frontend.
- It is a single full-stack Next.js App Router app: UI pages, API routes, server services, and background job triggers all sit in one codebase.
- The top-level docs/checklists are operational, not separate runtimes.
2. User-facing surfaces
- The app is organized around four main experiences: chat/navigator, knowledge graph (/mapa), study area (/estudio), and agenda (/agenda).
- Additional pages cover login/signup, settings, knowledge browsing, and the landing page.
- Shared UI is split between route-level pages in app/ and reusable components in src/components/.
3. Auth and tenant boundary
- There is a clear boundary between guest and authenticated users.
- Auth-related routing lives under app/(auth) and app/sign-in / app/sign-up, with middleware guarding access.
- Shared contexts like UserContext, SyllabusContext, and AuthModalContext carry user/session state into the client.
- The system also supports a guest mode where uploaded content is temporary and later cleaned up.
4. Backend is embedded in Next.js API routes
- The app/api/** tree is the server surface area.
- API route families map directly to product capabilities: chat, courses, graph, study, schedule, notes, upload, feedback, mastery, usage, user preferences, health, cron, and DB migration.
- This means the “backend” is not a separate service; it is serverless/route-based within the Next.js deployment.
5. Core persistence layer
- The app uses Neon Postgres as its primary database, with pgvector for embeddings.
- src/lib/schema.sql defines the database shape, and src/lib/db.ts is the shared database access entry point.
- Repository modules under src/lib/server/repositories/ isolate table-level access for chats, documents, chunks, graphs, schedules, mastery, study items, users, and jobs.
- That repository layer is the main boundary between application logic and storage.
6. Upload and ingestion pipeline
- Upload is multi-modal: PDF/link/text/blob routes all converge into the same ingestion flow.
- The flow validates, stores, and tracks documents first; processing can happen immediately or asynchronously.
- ingestion.service.ts, document.service.ts, and worker-trigger.ts coordinate parsing, chunking, and background work.
- The pipeline is designed so the initial request returns quickly while heavier enrichment happens later.
7. Async processing and job queue
- Background work is modeled as jobs in the database, not a separate queue service.
- Cron endpoints handle cleanup and processing retries, suggesting the app depends on scheduled server-side execution for durability.
- The README and code structure point to a DB-backed job system with atomic claiming and stuck-job recovery.
- This is important for architecture diagrams because ingestion is split into sync upload plus async enrichment.
8. RAG/chat subsystem
- Chat is a grounded retrieval-augmented generation flow, not a generic LLM chat.
- Retrieval lives in src/lib/server/rag/retrieval/ and retrieval.service.ts, combining vector similarity with lexical/hybrid ranking.
- Chat orchestration includes conversation history, agenda context, and citations; the route layer exposes chat history, message posting, model listing, and SSE-like streaming behavior.
- The chat UI is separated into a dedicated feature area under src/features/chat/ and src/components/navigator/.
9. Knowledge graph, schedule, and study generation
- Graph generation is its own server-side subsystem (graph.service.ts, graph-gen.ts, cross-graph.service.ts), with routes for fetching and reprocessing syllabus graphs.
- Schedule generation is separate but related, feeding agenda and review recommendations.
- Study content generation is handled by a dedicated RAG/study pipeline with specialized agents and tools, producing flashcards, quizzes, summaries, and review material.
- These subsystems share the same stored syllabus/document data but produce different derived artifacts.
10. AI orchestration and safety boundaries
- LLM access is abstracted through src/lib/llm/, with provider adapters and routing across model vendors.
- Tool use is explicit: study/recommendation/schedule/context retrieval tools live under src/lib/tools/.
- Guardrails, validation schemas, rate limiting, logging, tracing, and metering are all separated into their own libraries, which is a strong signal that generation is controlled and observable.
- This separation matters in the diagram: prompts, tools, retrieval, and output validation form a pipeline around the model, not a single monolith call.
11. Client-side feature structure
- The UI is organized by domain rather than by generic components.
- src/components/estudio, navigator, agenda, and auth hold feature-specific UI, while src/components/ui contains the shared design system primitives.
- Client-side state is split by concern: chat context, syllabus context, user context, and chat hooks orchestrate UI-to-API interactions.
- The graph editor uses a dedicated canvas component and appears to be a major interactive frontend subsystem.
12. Cross-cutting infrastructure
- Optional Redis caching/rate limiting is supported through Upstash with an in-memory fallback.
- Observability utilities are first-class: logger, timing, and trace modules suggest the app instruments server flows.
- CI is GitHub Actions, running type checks and a fairly broad Vitest suite.
- Deployment is Vercel-focused, matching the single-app Next.js architecture.
13. How data flows end-to-end
- A student uploads syllabus material.
- The document is parsed and stored, then asynchronously enriched into chunks, embeddings, graph nodes, schedule data, and study artifacts.
- The chat subsystem retrieves grounded context from those stored chunks and derived artifacts.
- The study and agenda subsystems consume the same underlying syllabus data but present it through different user workflows.
14. What to draw as the main boundaries
- One boundary is the browser/UI versus Next.js server routes.
- Another is route handlers versus service/repository layers.
- Inside the server, the key subsystem boundaries are ingestion, retrieval/chat, graph/schedule/study generation, and persistence/job management.
- The database is the central integration point tying those subsystems together.
Main entry points: page.tsx Landing · chat.repo.ts Repositories · retrieval.service.ts RAG Core · ingestion.service.ts Ingestion
Components 29
Client UI
Browser-facing pages, feature components, and shared client state.
- Landing · Public entry page and top-level navigation surface.
syllabus-navigator/frontend/app/page.tsx - Auth Pages · Login and signup flows plus auth layout.
syllabus-navigator/frontend/app/(auth)/layout.tsx - Navigator · Chat-centric browsing experience with dedicated components and feature hooks.
syllabus-navigator/frontend/src/components/navigator/chat-thread.tsx - Knowledge Map · Graph exploration surface for syllabus knowledge maps.
syllabus-navigator/frontend/app/mapa/page.tsx - Study Area · Flashcards, quizzes, mastery, and review workflows.
syllabus-navigator/frontend/src/components/estudio/flashcards-view.tsx - Agenda · Calendar and daily notes experience for planning and review.
syllabus-navigator/frontend/src/components/agenda/month-calendar.tsx - Settings · User preference and account settings surface.
syllabus-navigator/frontend/app/settings/page.tsx - Client State · User, syllabus, auth modal, and chat context providers/hooks.
syllabus-navigator/frontend/src/context/UserContext.tsx
Route API
Next.js App Router server surface exposed under app/api.
- Chat API · Chat history, message posting, model listing, and conversation detail routes.
syllabus-navigator/frontend/app/api/chat/[chatId]/route.ts - Upload API · Multi-modal upload entrypoints for text, link, blob, list, processing, and course linking.
syllabus-navigator/frontend/app/api/upload/route.ts - Graph API · Syllabus graph fetch, cross-graph, and reprocess endpoints.
syllabus-navigator/frontend/app/api/graph/[syllabusId]/route.ts - Study API · Study generation, quiz, review, stats, and session endpoints.
syllabus-navigator/frontend/app/api/study/[syllabusId]/route.ts - Schedule API · Agenda and schedule generation endpoints.
syllabus-navigator/frontend/app/api/schedule/route.ts - Courses API · Course CRUD and course-specific syllabus handling.
syllabus-navigator/frontend/app/api/courses/route.ts - Ops API · Health, cron cleanup/process, DB migration, feedback, usage, notes, mastery, and preferences endpoints.
syllabus-navigator/frontend/app/api/health/route.ts
Server Core
Ingestion, RAG, generation, orchestration, and application services.
- Ingestion · Validates uploads, stores documents, chunks content, and triggers asynchronous enrichment.
syllabus-navigator/frontend/src/lib/server/services/ingestion.service.ts - RAG Core · Retrieval, hybrid ranking, chat orchestration, and grounded response assembly.
syllabus-navigator/frontend/src/lib/server/services/retrieval.service.ts - Graph Gen · Builds and refreshes syllabus graphs, including cross-graph synthesis.
syllabus-navigator/frontend/src/lib/server/services/graph.service.ts - Study Gen · Produces flashcards, quizzes, summaries, and review materials.
syllabus-navigator/frontend/src/lib/server/services/study.service.ts - Schedule Gen · Creates study agendas and review schedules from syllabus data.
syllabus-navigator/frontend/src/lib/server/services/schedule.service.ts - Job Runner · DB-backed worker trigger, cron processing, cleanup, and retry recovery.
syllabus-navigator/frontend/src/lib/server/services/worker-trigger.ts
Persistence
Database, repositories, storage, and shared data access boundaries.
- DB Layer · Shared database entry point and schema definition for Neon Postgres plus pgvector.
syllabus-navigator/frontend/src/lib/db.ts - Repositories · Table-level persistence modules for chats, documents, chunks, graphs, schedules, mastery, study items, users, and jobs.
syllabus-navigator/frontend/src/lib/server/repositories/chat.repo.ts - Blob Storage · Server-side blob handling used by upload flows.
syllabus-navigator/frontend/src/lib/server/storage/blob.ts
Infra
Auth, cache, observability, validation, and external model integrations.
- LLM Gateway · Provider adapters, routing, embeddings, and generation wrappers across vendors.
syllabus-navigator/frontend/src/lib/llm/router.ts - Guardrails · Input/output validation, API schemas, and safety boundaries around generation.
syllabus-navigator/frontend/src/lib/guardrails/index.ts - Tools · Explicit tool registry for retrieval, recommendations, scheduling, and review recording.
syllabus-navigator/frontend/src/lib/tools/registry.ts - Observability · Logging, timing, tracing, metering, and rate limiting support.
syllabus-navigator/frontend/src/lib/observability/logger.ts - Auth Boundary · Middleware and server auth helpers enforcing guest versus authenticated access.
syllabus-navigator/frontend/middleware.ts
Connections 37
- Landing → Auth Pages: entry · Public pages lead into login/signup flows for authenticated access.
- Landing → Navigator: open chat · Primary user journey into the navigator experience.
- Landing → Knowledge Map: browse graph · Users move from landing into the knowledge map.
- Landing → Study Area: study · Users access generated study material from the main app.
- Landing → Agenda: plan · Users open agenda and schedule views.
- Landing → Settings: settings · User preferences and account configuration.
- Auth Pages → Auth Boundary: guarded by · Auth routes and middleware define the access boundary.
- Client State → Navigator: state · Client contexts and chat hooks feed the navigator UI.
- Client State → Study Area: state · Shared syllabus and user state powers study workflows.
- Client State → Agenda: state · Shared user/syllabus state powers agenda views.
- Navigator → Chat API: chat API · Chat UI posts messages and streams responses through the API.
- Knowledge Map → Graph API: graph API · Knowledge map fetches and refreshes graph data.
- Study Area → Study API: study API · Study UI loads generated sets, quizzes, and review state.
- Agenda → Schedule API: schedule API · Agenda UI consumes generated schedule data.
- Settings → Ops API: prefs · Settings and account operations use user preference endpoints.
- Upload API → Ingestion: ingest · All upload variants converge into the ingestion pipeline.
- Chat API → RAG Core: retrieve · Chat routes delegate grounded answer generation to the RAG subsystem.
- Graph API → Graph Gen: build graphs · Graph routes fetch and reprocess syllabus graph artifacts.
- Study API → Study Gen: generate study · Study routes orchestrate flashcards, quizzes, and reviews.
- Schedule API → Schedule Gen: generate schedule · Schedule routes compute agenda and review plans.
- Ops API → Job Runner: cron/jobs · Operational routes drive cleanup, retries, and job processing.
- Ingestion → Blob Storage: store files · Uploaded blobs are persisted before downstream enrichment.
- Ingestion → Repositories: track docs · Documents, chunks, and job state are recorded through repositories.
- RAG Core → LLM Gateway: model calls · Retrieval and chat orchestration call into routed model providers.
- RAG Core → Tools: tool use · Retrieval and recommendation tools are invoked explicitly by the orchestration layer.
- RAG Core → Repositories: read context · Chat grounding pulls from chats, chunks, and related stored artifacts.
- Graph Gen → Repositories: persist graphs · Graph generation writes nodes, edges, and cross-graph results.
- Study Gen → Repositories: persist study · Study generation stores study items, mastery, and review state.
- Schedule Gen → Repositories: persist schedule · Schedule output is stored for agenda and review workflows.
- Job Runner → Repositories: claim jobs · Job execution and recovery are coordinated through database-backed claims.
- Repositories → DB Layer: sql · Repository modules are the main boundary over the shared database connection.
- Guardrails → Chat API: validate · API inputs and outputs are schema-checked around generation flows.
- Guardrails → Upload API: validate · Upload routes are validated before persistence or processing.
- Observability → RAG Core: trace · Chat and retrieval flows are instrumented for logging and timing.
- Observability → Ingestion: trace · Ingestion and background work are observable and rate-limited.
- Auth Boundary → Ops API: protect · Server routes enforce authenticated versus guest access.
- Auth Boundary → Upload API: protect · Upload and content handling respect the auth boundary and guest mode.