# chavesgabriel012-svg/edukemonos architecture

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

- Interactive diagram: https://gitdiagram.com/chavesgabriel012-svg/edukemonos
- Repository: https://github.com/chavesgabriel012-svg/edukemonos

## Overview

Eduka is an open, AI-assisted learning platform for Costa Rican public-school students. Its main learner journey is choosing a grade, subject, and unit, then learning, practicing, and optionally asking Kemo; diagnostics and saved progress support that journey. Separate educator workflows manage sections and inspect learning analytics, while reviewers approve generated content. The README also documents curriculum ingestion and AI content generation. Several routes and data-access details are unsampled, so undocumented links are omitted; README-backed links describe capabilities rather than implying inspected implementation.

Main entry points: [`apps/web/src/app/api/tutor/route.ts`](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/api/tutor/route.ts) (Tutor endpoint), [`apps/web/src/app/(app)/unidad/[id]/practice.tsx`](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unidad/%5Bid%5D/practice.tsx) (Practice), [`packages/ai/src/tutor/index.ts`](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/tutor/index.ts) (Tutor logic), [`packages/ai/src/client.ts`](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/client.ts) (AI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learn["Student learning"]
  node_catalog["Study catalog<br/>[page.tsx]"]
  node_unit["Unit workspace<br/>[page.tsx]"]
  node_practice["Practice<br/>[practice.tsx]"]
  node_diagnostic["Diagnostic<br/>[page.tsx]"]
  node_progress["Learning progress<br/>[learn.ts]"]
  node_join["Section joining<br/>[page.tsx]"]
  node_tutor_route["Tutor endpoint<br/>[route.ts]"]
end

subgraph group_educators["Educator workflows"]
  node_teacher["Teacher workspace<br/>[page.tsx]"]
  node_teacher_metrics["Section analytics<br/>[teacher.ts]"]
  node_review["Content review<br/>[page.tsx]"]
  node_content_review["Review rules<br/>[content-review.ts]"]
end

subgraph group_content["Curriculum and content"]
  node_ingest["Source ingestion<br/>[structure.ts]"]
  node_generation["Content generation<br/>[content.ts]"]
  node_items["Learning items<br/>[items.ts]"]
  node_curriculum_learning["Learning model<br/>[learning.ts]"]
end

subgraph group_ai["AI services"]
  node_ai_tutor["Tutor logic<br/>[index.ts]"]
  node_tutor_prompts["Tutor prompts<br/>[tutor.ts]"]
  node_tutor_safety["Safety and output<br/>[safety.ts]"]
  node_ai_client["AI client<br/>[client.ts]"]
  node_anthropic["Anthropic adapter<br/>[anthropic.ts]"]
  node_openai["OpenAI adapter<br/>[openai.ts]"]
end

node_learner(("Student"))
node_teacher_actor(("Teacher or reviewer"))
node_mep["MEP sources"]
node_database[("Supabase")]
node_model_services{{"AI providers"}}

node_learner -->|"chooses study"| node_catalog
node_catalog -->|"opens unit"| node_unit
node_unit -->|"starts practice"| node_practice
node_learner -->|"takes diagnostic"| node_diagnostic
node_learner -->|"joins section"| node_join
node_learner -->|"asks tutor"| node_tutor_route
node_tutor_route -->|"reads and writes session"| node_database
node_tutor_route -->|"uses tutor functions"| node_ai_tutor
node_ai_tutor -->|"builds prompts"| node_tutor_prompts
node_ai_tutor -->|"uses safety note"| node_tutor_safety
node_tutor_route -->|"streams AI response"| node_ai_client
node_ai_client -->|"dispatches provider calls"| node_anthropic
node_ai_client -->|"dispatches provider calls"| node_openai
node_anthropic -.->|"sends model requests"| node_model_services
node_openai -->|"sends model requests"| node_model_services
node_teacher_actor -->|"manages classes"| node_teacher
node_teacher -->|"views analytics"| node_teacher_metrics
node_teacher_actor -->|"reviews content"| node_review
node_review -.->|"applies review"| node_content_review
node_mep -->|"provides programs"| node_ingest
node_ingest -.->|"prepares curriculum"| node_generation
node_generation -->|"creates study items"| node_items
node_practice -->|"submits attempts"| node_database
node_practice -.->|"updates learning progress"| node_progress
node_diagnostic -->|"uses verified items"| node_items
node_teacher_metrics -->|"uses mastery thresholds"| node_curriculum_learning

click node_catalog "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/estudiar/page.tsx"
click node_unit "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unidad/%5Bid%5D/page.tsx"
click node_practice "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unidad/%5Bid%5D/practice.tsx"
click node_diagnostic "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/estudiar/%5Bgrado%5D/%5Bmateria%5D/diagnostico/page.tsx"
click node_progress "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/lib/learn.ts"
click node_join "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unirme/page.tsx"
click node_tutor_route "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/api/tutor/route.ts"
click node_teacher "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/docente/page.tsx"
click node_teacher_metrics "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/curriculum/src/teacher.ts"
click node_review "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/revisar/%5Bid%5D/contenido/page.tsx"
click node_content_review "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/lib/content-review.ts"
click node_ingest "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/scripts/ingest/src/structure.ts"
click node_generation "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/scripts/ingest/src/content.ts"
click node_items "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/curriculum/src/items.ts"
click node_curriculum_learning "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/curriculum/src/learning.ts"
click node_ai_tutor "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/tutor/index.ts"
click node_tutor_prompts "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/prompts/tutor.ts"
click node_tutor_safety "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/tutor/safety.ts"
click node_ai_client "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/client.ts"
click node_anthropic "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/providers/anthropic.ts"
click node_openai "https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/providers/openai.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_catalog,node_unit,node_practice,node_diagnostic,node_progress,node_join,node_tutor_route,node_teacher_actor toneBlue
class node_teacher,node_teacher_metrics,node_review,node_content_review,node_database toneAmber
class node_ingest,node_generation,node_items,node_curriculum_learning toneMint
class node_ai_tutor,node_tutor_prompts,node_tutor_safety,node_ai_client,node_anthropic,node_openai toneRose
class node_learner,node_mep,node_model_services toneIndigo
```

## Components

### Student learning

- [Study catalog](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/estudiar/page.tsx): `apps/web/src/app/(app)/estudiar/page.tsx`
- [Unit workspace](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unidad/%5Bid%5D/page.tsx): `apps/web/src/app/(app)/unidad/[id]/page.tsx`
- [Practice](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unidad/%5Bid%5D/practice.tsx): `apps/web/src/app/(app)/unidad/[id]/practice.tsx`
- [Diagnostic](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/estudiar/%5Bgrado%5D/%5Bmateria%5D/diagnostico/page.tsx): `apps/web/src/app/(app)/estudiar/[grado]/[materia]/diagnostico/page.tsx`
- [Learning progress](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/lib/learn.ts): `apps/web/src/lib/learn.ts`
- [Section joining](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/unirme/page.tsx): `apps/web/src/app/(app)/unirme/page.tsx`
- [Tutor endpoint](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/api/tutor/route.ts): `apps/web/src/app/api/tutor/route.ts`

### Educator workflows

- [Teacher workspace](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/docente/page.tsx): `apps/web/src/app/(app)/docente/page.tsx`
- [Section analytics](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/curriculum/src/teacher.ts): `packages/curriculum/src/teacher.ts`
- [Content review](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/app/(app)/revisar/%5Bid%5D/contenido/page.tsx): `apps/web/src/app/(app)/revisar/[id]/contenido/page.tsx`
- [Review rules](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/apps/web/src/lib/content-review.ts): `apps/web/src/lib/content-review.ts`

### Curriculum and content

- [Source ingestion](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/scripts/ingest/src/structure.ts): `scripts/ingest/src/structure.ts`
- [Content generation](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/scripts/ingest/src/content.ts): `scripts/ingest/src/content.ts`
- [Learning items](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/curriculum/src/items.ts): `packages/curriculum/src/items.ts`
- [Learning model](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/curriculum/src/learning.ts): `packages/curriculum/src/learning.ts`

### AI services

- [Tutor logic](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/tutor/index.ts): `packages/ai/src/tutor/index.ts`
- [Tutor prompts](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/prompts/tutor.ts): `packages/ai/src/prompts/tutor.ts`
- [Safety and output](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/tutor/safety.ts): `packages/ai/src/tutor/safety.ts`
- [AI client](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/client.ts): `packages/ai/src/client.ts`
- [Anthropic adapter](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/providers/anthropic.ts): `packages/ai/src/providers/anthropic.ts`
- [OpenAI adapter](https://github.com/chavesgabriel012-svg/edukemonos/blob/main/packages/ai/src/providers/openai.ts): `packages/ai/src/providers/openai.ts`

### Other components

- **Student**
- **Teacher or reviewer**
- **MEP sources**
- **Supabase**
- **AI providers**

## Connections

- Student → Study catalog: chooses study (evidence: `README.md`)
- Study catalog → Unit workspace: opens unit (evidence: `README.md`)
- Unit workspace → Practice: starts practice (evidence: `README.md`)
- Student → Diagnostic: takes diagnostic (evidence: `README.md`)
- Student → Section joining: joins section (evidence: `README.md`)
- Student → Tutor endpoint: asks tutor (evidence: `README.md`)
- Tutor endpoint → Supabase: reads and writes session (evidence: `apps/web/src/app/api/tutor/route.ts`)
- Tutor endpoint → Tutor logic: uses tutor functions (evidence: `apps/web/src/app/api/tutor/route.ts`)
- Tutor logic → Tutor prompts: builds prompts (evidence: `packages/ai/src/tutor/index.ts`)
- Tutor logic → Safety and output: uses safety note (evidence: `packages/ai/src/tutor/index.ts`)
- Tutor endpoint → AI client: streams AI response (evidence: `apps/web/src/app/api/tutor/route.ts`)
- AI client → Anthropic adapter: dispatches provider calls (evidence: `packages/ai/src/client.ts`)
- AI client → OpenAI adapter: dispatches provider calls (evidence: `packages/ai/src/client.ts`)
- Anthropic adapter → AI providers: sends model requests
- OpenAI adapter → AI providers: sends model requests (evidence: `packages/ai/src/providers/openai.ts`)
- Teacher or reviewer → Teacher workspace: manages classes (evidence: `README.md`)
- Teacher workspace → Section analytics: views analytics (evidence: `README.md`)
- Teacher or reviewer → Content review: reviews content (evidence: `README.md`)
- Content review → Review rules: applies review
- MEP sources → Source ingestion: provides programs (evidence: `README.md`)
- Source ingestion → Content generation: prepares curriculum
- Content generation → Learning items: creates study items (evidence: `README.md`)
- Practice → Supabase: submits attempts (evidence: `README.md`)
- Practice → Learning progress: updates learning progress
- Diagnostic → Learning items: uses verified items (evidence: `README.md`)
- Section analytics → Learning model: uses mastery thresholds (evidence: `packages/curriculum/src/teacher.ts`)
