# relichtyy/navigator architecture

> Architecture diagram of the GitHub repository relichtyy/navigator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/relichtyy/navigator
- Repository: https://github.com/relichtyy/navigator

## Overview

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: [`syllabus-navigator/frontend/app/page.tsx`](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/page.tsx) (Landing), [`syllabus-navigator/frontend/src/lib/server/repositories/chat.repo.ts`](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/repositories/chat.repo.ts) (Repositories), [`syllabus-navigator/frontend/src/lib/server/services/retrieval.service.ts`](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/retrieval.service.ts) (RAG Core), [`syllabus-navigator/frontend/src/lib/server/services/ingestion.service.ts`](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/ingestion.service.ts) (Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_ui["Client UI"]
  node_ui_landing["Landing<br/>app page<br/>[page.tsx]"]
  node_ui_auth["Auth Pages<br/>route group<br/>[layout.tsx]"]
  node_ui_navigator["Navigator<br/>feature UI<br/>[chat-thread.tsx]"]
  node_ui_mapa["Knowledge Map<br/>app page<br/>[page.tsx]"]
  node_ui_estudio["Study Area<br/>feature UI"]
  node_ui_agenda["Agenda<br/>feature UI<br/>[month-calendar.tsx]"]
  node_ui_settings["Settings<br/>app page<br/>[page.tsx]"]
  node_ui_contexts["Client State<br/>contexts<br/>[UserContext.tsx]"]
end

subgraph group_grp_api["Route API"]
  node_api_chat["Chat API<br/>route family<br/>[route.ts]"]
  node_api_upload["Upload API<br/>route family<br/>[route.ts]"]
  node_api_graph["Graph API<br/>route family<br/>[route.ts]"]
  node_api_study["Study API<br/>route family<br/>[route.ts]"]
  node_api_schedule["Schedule API<br/>route<br/>[route.ts]"]
  node_api_courses["Courses API<br/>route family<br/>[route.ts]"]
  node_api_admin["Ops API<br/>route family<br/>[route.ts]"]
end

subgraph group_grp_core["Server Core"]
  node_svc_ingest{{"Ingestion<br/>service pipeline"}}
  node_svc_rag{{"RAG Core<br/>service pipeline"}}
  node_svc_graph{{"Graph Gen<br/>generation service<br/>[graph.service.ts]"}}
  node_svc_study{{"Study Gen<br/>generation service<br/>[study.service.ts]"}}
  node_svc_schedule{{"Schedule Gen<br/>generation service"}}
  node_svc_jobs{{"Job Runner<br/>async jobs<br/>[worker-trigger.ts]"}}
end

subgraph group_grp_data["Persistence"]
  node_repo_db[("DB Layer<br/>database access<br/>[db.ts]")]
  node_repo_mod["Repositories<br/>repo modules<br/>[chat.repo.ts]"]
  node_blob_store[("Blob Storage<br/>object storage<br/>[blob.ts]")]
end

subgraph group_grp_infra["Infra"]
  node_infra_llm{{"LLM Gateway<br/>model routing<br/>[router.ts]"}}
  node_infra_guard["Guardrails<br/>validation<br/>[index.ts]"]
  node_infra_tools["Tools<br/>tooling<br/>[registry.ts]"]
  node_infra_obs["Observability<br/>telemetry<br/>[logger.ts]"]
  node_infra_auth["Auth Boundary<br/>middleware/auth<br/>[middleware.ts]"]
end

node_ui_landing -->|"entry"| node_ui_auth
node_ui_landing -->|"open chat"| node_ui_navigator
node_ui_landing -->|"browse graph"| node_ui_mapa
node_ui_landing -->|"study"| node_ui_estudio
node_ui_landing -->|"plan"| node_ui_agenda
node_ui_landing -->|"settings"| node_ui_settings
node_ui_auth -->|"guarded by"| node_infra_auth
node_ui_contexts -->|"state"| node_ui_navigator
node_ui_contexts -->|"state"| node_ui_estudio
node_ui_contexts -->|"state"| node_ui_agenda
node_ui_navigator -->|"chat API"| node_api_chat
node_ui_mapa -->|"graph API"| node_api_graph
node_ui_estudio -->|"study API"| node_api_study
node_ui_agenda -->|"schedule API"| node_api_schedule
node_ui_settings -->|"prefs"| node_api_admin
node_api_upload -->|"ingest"| node_svc_ingest
node_api_chat -->|"retrieve"| node_svc_rag
node_api_graph -->|"build graphs"| node_svc_graph
node_api_study -->|"generate study"| node_svc_study
node_api_schedule -->|"generate schedule"| node_svc_schedule
node_api_admin -->|"cron/jobs"| node_svc_jobs
node_svc_ingest -->|"store files"| node_blob_store
node_svc_ingest -->|"track docs"| node_repo_mod
node_svc_rag -->|"model calls"| node_infra_llm
node_svc_rag -->|"tool use"| node_infra_tools
node_svc_rag -->|"read context"| node_repo_mod
node_svc_graph -->|"persist graphs"| node_repo_mod
node_svc_study -->|"persist study"| node_repo_mod
node_svc_schedule -->|"persist schedule"| node_repo_mod
node_svc_jobs -->|"claim jobs"| node_repo_mod
node_repo_mod -->|"sql"| node_repo_db
node_infra_guard -->|"validate"| node_api_chat
node_infra_guard -->|"validate"| node_api_upload
node_infra_obs -->|"trace"| node_svc_rag
node_infra_obs -->|"trace"| node_svc_ingest
node_infra_auth -->|"protect"| node_api_admin
node_infra_auth -->|"protect"| node_api_upload

click node_ui_landing "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/page.tsx"
click node_ui_auth "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/(auth)/layout.tsx"
click node_ui_navigator "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/components/navigator/chat-thread.tsx"
click node_ui_mapa "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/mapa/page.tsx"
click node_ui_estudio "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/components/estudio/flashcards-view.tsx"
click node_ui_agenda "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/components/agenda/month-calendar.tsx"
click node_ui_settings "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/settings/page.tsx"
click node_ui_contexts "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/context/UserContext.tsx"
click node_api_chat "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/chat/[chatId]/route.ts"
click node_api_upload "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/upload/route.ts"
click node_api_graph "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/graph/[syllabusId]/route.ts"
click node_api_study "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/study/[syllabusId]/route.ts"
click node_api_schedule "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/schedule/route.ts"
click node_api_courses "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/courses/route.ts"
click node_api_admin "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/health/route.ts"
click node_svc_ingest "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/ingestion.service.ts"
click node_svc_rag "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/retrieval.service.ts"
click node_svc_graph "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/graph.service.ts"
click node_svc_study "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/study.service.ts"
click node_svc_schedule "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/schedule.service.ts"
click node_svc_jobs "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/worker-trigger.ts"
click node_repo_db "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/db.ts"
click node_repo_mod "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/repositories/chat.repo.ts"
click node_blob_store "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/storage/blob.ts"
click node_infra_llm "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/llm/router.ts"
click node_infra_guard "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/guardrails/index.ts"
click node_infra_tools "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/tools/registry.ts"
click node_infra_obs "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/observability/logger.ts"
click node_infra_auth "https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/middleware.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_landing,node_ui_auth,node_ui_navigator,node_ui_mapa,node_ui_estudio,node_ui_agenda,node_ui_settings,node_ui_contexts toneBlue
class node_api_chat,node_api_upload,node_api_graph,node_api_study,node_api_schedule,node_api_courses,node_api_admin toneAmber
class node_svc_ingest,node_svc_rag,node_svc_graph,node_svc_study,node_svc_schedule,node_svc_jobs toneMint
class node_repo_db,node_repo_mod,node_blob_store toneRose
class node_infra_llm,node_infra_guard,node_infra_tools,node_infra_obs,node_infra_auth toneIndigo
```

## Components

### Client UI

Browser-facing pages, feature components, and shared client state.

- [Landing](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/page.tsx): app page · Public entry page and top-level navigation surface. · `syllabus-navigator/frontend/app/page.tsx`
- [Auth Pages](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/(auth)/layout.tsx): route group · Login and signup flows plus auth layout. · `syllabus-navigator/frontend/app/(auth)/layout.tsx`
- [Navigator](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/components/navigator/chat-thread.tsx): feature UI · Chat-centric browsing experience with dedicated components and feature hooks. · `syllabus-navigator/frontend/src/components/navigator/chat-thread.tsx`
- [Knowledge Map](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/mapa/page.tsx): app page · Graph exploration surface for syllabus knowledge maps. · `syllabus-navigator/frontend/app/mapa/page.tsx`
- [Study Area](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/components/estudio/flashcards-view.tsx): feature UI · Flashcards, quizzes, mastery, and review workflows. · `syllabus-navigator/frontend/src/components/estudio/flashcards-view.tsx`
- [Agenda](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/components/agenda/month-calendar.tsx): feature UI · Calendar and daily notes experience for planning and review. · `syllabus-navigator/frontend/src/components/agenda/month-calendar.tsx`
- [Settings](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/settings/page.tsx): app page · User preference and account settings surface. · `syllabus-navigator/frontend/app/settings/page.tsx`
- [Client State](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/context/UserContext.tsx): contexts · 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](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/chat/[chatId]/route.ts): route family · Chat history, message posting, model listing, and conversation detail routes. · `syllabus-navigator/frontend/app/api/chat/[chatId]/route.ts`
- [Upload API](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/upload/route.ts): route family · Multi-modal upload entrypoints for text, link, blob, list, processing, and course linking. · `syllabus-navigator/frontend/app/api/upload/route.ts`
- [Graph API](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/graph/[syllabusId]/route.ts): route family · Syllabus graph fetch, cross-graph, and reprocess endpoints. · `syllabus-navigator/frontend/app/api/graph/[syllabusId]/route.ts`
- [Study API](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/study/[syllabusId]/route.ts): route family · Study generation, quiz, review, stats, and session endpoints. · `syllabus-navigator/frontend/app/api/study/[syllabusId]/route.ts`
- [Schedule API](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/schedule/route.ts): route · Agenda and schedule generation endpoints. · `syllabus-navigator/frontend/app/api/schedule/route.ts`
- [Courses API](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/courses/route.ts): route family · Course CRUD and course-specific syllabus handling. · `syllabus-navigator/frontend/app/api/courses/route.ts`
- [Ops API](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/app/api/health/route.ts): route family · 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](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/ingestion.service.ts): service pipeline · Validates uploads, stores documents, chunks content, and triggers asynchronous enrichment. · `syllabus-navigator/frontend/src/lib/server/services/ingestion.service.ts`
- [RAG Core](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/retrieval.service.ts): service pipeline · Retrieval, hybrid ranking, chat orchestration, and grounded response assembly. · `syllabus-navigator/frontend/src/lib/server/services/retrieval.service.ts`
- [Graph Gen](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/graph.service.ts): generation service · Builds and refreshes syllabus graphs, including cross-graph synthesis. · `syllabus-navigator/frontend/src/lib/server/services/graph.service.ts`
- [Study Gen](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/study.service.ts): generation service · Produces flashcards, quizzes, summaries, and review materials. · `syllabus-navigator/frontend/src/lib/server/services/study.service.ts`
- [Schedule Gen](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/schedule.service.ts): generation service · Creates study agendas and review schedules from syllabus data. · `syllabus-navigator/frontend/src/lib/server/services/schedule.service.ts`
- [Job Runner](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/services/worker-trigger.ts): async jobs · 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](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/db.ts): database access · Shared database entry point and schema definition for Neon Postgres plus pgvector. · `syllabus-navigator/frontend/src/lib/db.ts`
- [Repositories](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/repositories/chat.repo.ts): repo modules · 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](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/server/storage/blob.ts): object 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](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/llm/router.ts): model routing · Provider adapters, routing, embeddings, and generation wrappers across vendors. · `syllabus-navigator/frontend/src/lib/llm/router.ts`
- [Guardrails](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/guardrails/index.ts): validation · Input/output validation, API schemas, and safety boundaries around generation. · `syllabus-navigator/frontend/src/lib/guardrails/index.ts`
- [Tools](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/tools/registry.ts): tooling · Explicit tool registry for retrieval, recommendations, scheduling, and review recording. · `syllabus-navigator/frontend/src/lib/tools/registry.ts`
- [Observability](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/src/lib/observability/logger.ts): telemetry · Logging, timing, tracing, metering, and rate limiting support. · `syllabus-navigator/frontend/src/lib/observability/logger.ts`
- [Auth Boundary](https://github.com/relichtyy/navigator/blob/main/syllabus-navigator/frontend/middleware.ts): middleware/auth · Middleware and server auth helpers enforcing guest versus authenticated access. · `syllabus-navigator/frontend/middleware.ts`

## Connections

- 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.
