# lucianomaciel10/crear-cuestionarios architecture

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

- Interactive diagram: https://gitdiagram.com/lucianomaciel10/crear-cuestionarios
- Repository: https://github.com/lucianomaciel10/crear-cuestionarios

## Overview

1. **Overall shape**
   - This is a **React + TypeScript + Vite single-page application** with most product logic implemented in TypeScript services inside `src/services`.
   - It is not a traditional backend-heavy app; the architecture is **client-first**, with local persistence and a small optional API surface.

2. **Primary user-facing subsystems**
   - The UI is organized around learning workflows: **Subjects**, **Materials**, **Flashcards**, **Quizzes**, and **Statistics**.
   - Pages in `src/pages` map to those workflows, while reusable UI lives in `src/components` and is split into `common`, `domain`, and `layout`.

3. **Application shell and navigation**
   - `src/main.tsx`, `src/App.tsx`, and `src/routes/index.tsx` define the SPA bootstrapping and routing.
   - `src/components/layout/MainLayout.tsx` and common components like `Navbar`, `Modal`, `Toast`, and `ThemeToggle` provide the persistent shell and global UI behavior.

4. **State and cross-cutting concerns**
   - Theme and toast are handled as shared app concerns through `src/contexts/ThemeContext.tsx` and `src/contexts/ToastContext.ts`, with hooks in `src/hooks/useTheme.ts` and `src/hooks/useToast.ts`.
   - These are presentation-level concerns, separate from the learning/domain logic.

5. **Local data model and persistence**
   - The app uses **Dexie/IndexedDB** via `src/data/db/dexie-db.ts` as the persistent store.
   - Domain entities are modeled in `src/data/models` and include subjects (`materia`), materials, knowledge nodes, questions, tags/labels (`etiqueta`), and spaced-repetition state.
   - This makes the app effectively **offline-capable / local-first**, with the browser database acting as the system of record.

6. **Core domain services**
   - The main business logic lives in `src/services`, and this is where the architecture becomes interesting.
   - `subject.service.ts`, `material.service.ts`, `knowledge-node.service.ts`, `question.service.ts`, and `flashcard.service.ts` encapsulate domain operations instead of putting logic in components.
   - UI components and hooks call these services, which then coordinate parsing, extraction, generation, and persistence.

7. **Material ingestion pipeline**
   - Raw learning content enters through the **material parsing layer** in `src/services/material-parser`.
   - Separate parsers exist for **PDF, DOCX, PPTX, Markdown, text**, plus a text-processing/conversion step.
   - The expected flow is: user adds material → parser normalizes content → downstream extraction services consume structured text.

8. **Knowledge extraction and concept discovery**
   - `src/services/knowledge-extraction` contains the concept/knowledge extraction pipeline.
   - It supports multiple providers: a **regex-based provider** and an **AI provider**, which are coordinated by an extraction service.
   - There is also an API file at `api/extract-concepts.ts`, suggesting a serverless endpoint for concept extraction when the app needs a backend call rather than purely local processing.

9. **Corpus and batch processing**
   - The presence of `corpus-processing` and `batch-processing` indicates the app can aggregate material into larger corpora and process items in batches.
   - `batch-cache.ts` and `batch-processor.ts` suggest caching and throttling/retry behavior around expensive work like extraction or generation.
   - `corpus-builder.ts` likely assembles the normalized educational corpus used by the rest of the system.

10. **Learning engine: spaced repetition and adaptation**
    - `src/services/spaced-repetition` implements the review scheduling model, including an `sm2-algorithm.ts` and `sm2-engine.ts`.
    - `knowledge-node-updater.ts` connects review outcomes back to knowledge-node mastery state.
    - `src/services/adaptive-learning/adaptive-engine.ts` adds personalization on top of spacing, likely influencing what to review or generate next.

11. **Question and quiz subsystem**
    - `src/services/question-generator` provides generator strategies for **multiple-choice** and **boolean** questions.
    - `question.service.ts` likely orchestrates generation, storage, and retrieval.
    - The quiz UI is split between management and play modes (`QuizManagement`, `QuizPlayer`), with `useQuizEngine` mediating state and progression.

12. **Flashcards and mastery visualization**
    - Flashcard-related logic is separated into `flashcard.service.ts` and UI components like `FlashcardFlip` and `QualityButtons`.
    - Statistics and understanding feedback are surfaced through `TopicMasteryChart` and `WeakPointsList`, which likely consume aggregated mastery data from knowledge nodes and spaced-repetition results.

13. **Hooks as the UI-to-domain boundary**
    - Hooks such as `useMaterials.ts` and `useSubjects.ts` are the main integration layer between React components and the service/model layer.
    - They hide persistence and domain orchestration details from the UI, which keeps the page components relatively thin.

14. **Infrastructure and build/deploy**
    - The repo is built with **Vite**, TypeScript, Tailwind/PostCSS, and ESLint; deployment targets appear to include **Vercel** (`vercel.json`, `vercel-dev.js`, `.vercelignore`).
    - `api/` suggests a serverless function boundary, but the majority of runtime behavior remains in the browser.

15. **How to draw the architecture**
    - A clean diagram would show: **React pages/components** at the top, **hooks** as the glue layer, **domain services** in the middle, and **IndexedDB/Dexie** as the persistence layer.
    - A separate branch should show the **material ingestion/extraction pipeline** feeding into **knowledge nodes**, which then feed **quiz generation** and **spaced repetition/adaptive learning**.
    - The only notable external boundary is the **AI/concept extraction path**, which may go through the `api/extract-concepts.ts` serverless endpoint and/or the AI provider abstraction.

Main entry points: [`src/routes/index.tsx`](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/routes/index.tsx) (Router), [`src/services/knowledge-node.service.ts`](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/knowledge-node.service.ts) (Knowledge nodes), [`src/services/material.service.ts`](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/material.service.ts) (Material service), [`src/hooks/useQuizEngine.ts`](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useQuizEngine.ts) (useQuizEngine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main(("main.tsx<br/>boot<br/>[main.tsx]"))
  node_app["App<br/>shell<br/>[App.tsx]"]
  node_routes["Router<br/>routing<br/>[index.tsx]"]
  node_layout["Main layout<br/>[MainLayout.tsx]"]
  node_dashboard["Dashboard<br/>page<br/>[Dashboard.tsx]"]
  node_materials["Materials<br/>page<br/>[MaterialsPage.tsx]"]
  node_flashcards["Flashcards<br/>page<br/>[Flashcards.tsx]"]
  node_quizzes["Quizzes<br/>page<br/>[QuizManagement.tsx]"]
  node_quiz_player["Quiz player<br/>page<br/>[QuizPlayer.tsx]"]
  node_stats["Statistics<br/>page<br/>[Statistics.tsx]"]
  node_subjects_hook(("useSubjects<br/>hook<br/>[useSubjects.ts]"))
  node_materials_hook(("useMaterials<br/>hook<br/>[useMaterials.ts]"))
  node_quiz_hook(("useQuizEngine<br/>hook<br/>[useQuizEngine.ts]"))
end

subgraph group_domain["Domain Services"]
  node_subject_service["Subject service<br/>[subject.service.ts]"]
  node_material_service["Material service"]
  node_knowledge_service["Knowledge nodes"]
  node_question_service["Question service"]
  node_flashcard_service["Flashcard service"]
  node_material_parser["Material parser<br/>pipeline"]
  node_extraction_service["Extraction service<br/>pipeline"]
  node_adaptive_engine["Adaptive engine<br/>learning<br/>[adaptive-engine.ts]"]
  node_sm2_engine["SM-2 engine<br/>scheduler<br/>[sm2-engine.ts]"]
end

subgraph group_data["Data & Infra"]
  node_db[("Dexie DB<br/>indexeddb<br/>[dexie-db.ts]")]
  node_models["Domain models<br/>schema"]
  node_ai_api{{"Concept API<br/>serverless"}}
end

node_main -->|"boots"| node_app
node_app -->|"navigates"| node_routes
node_routes -->|"wraps"| node_layout
node_routes -->|"loads"| node_dashboard
node_routes -->|"loads"| node_materials
node_routes -->|"loads"| node_flashcards
node_routes -->|"loads"| node_quizzes
node_routes -->|"loads"| node_quiz_player
node_routes -->|"loads"| node_stats
node_dashboard -->|"reads"| node_subjects_hook
node_materials -->|"reads"| node_materials_hook
node_flashcards -->|"drives"| node_quiz_hook
node_quizzes -->|"drives"| node_quiz_hook
node_quiz_player -->|"drives"| node_quiz_hook
node_subjects_hook -->|"calls"| node_subject_service
node_materials_hook -->|"calls"| node_material_service
node_quiz_hook -->|"uses"| node_question_service
node_quiz_hook -->|"uses"| node_flashcard_service
node_subject_service -->|"persists"| node_db
node_material_service -->|"persists"| node_db
node_material_service -->|"ingests"| node_material_parser
node_material_service -->|"derives"| node_knowledge_service
node_knowledge_service -->|"extracts"| node_extraction_service
node_extraction_service -.->|"optionally calls"| node_ai_api
node_knowledge_service -->|"updates"| node_sm2_engine
node_sm2_engine -->|"feeds"| node_adaptive_engine
node_question_service -->|"builds from"| node_knowledge_service
node_flashcard_service -->|"tracks"| node_knowledge_service
node_knowledge_service -->|"uses"| node_models
node_subject_service -->|"uses"| node_models
node_material_service -->|"uses"| node_models
node_question_service -->|"uses"| node_models

click node_main "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/main.tsx"
click node_app "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/App.tsx"
click node_routes "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/routes/index.tsx"
click node_layout "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/components/layout/MainLayout.tsx"
click node_dashboard "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/Dashboard.tsx"
click node_materials "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/MaterialsPage.tsx"
click node_flashcards "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/Flashcards.tsx"
click node_quizzes "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/QuizManagement.tsx"
click node_quiz_player "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/QuizPlayer.tsx"
click node_stats "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/Statistics.tsx"
click node_subjects_hook "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useSubjects.ts"
click node_materials_hook "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useMaterials.ts"
click node_quiz_hook "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useQuizEngine.ts"
click node_subject_service "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/subject.service.ts"
click node_material_service "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/material.service.ts"
click node_knowledge_service "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/knowledge-node.service.ts"
click node_question_service "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/question.service.ts"
click node_flashcard_service "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/flashcard.service.ts"
click node_material_parser "https://github.com/lucianomaciel10/crear-cuestionarios/tree/main/src/services/material-parser"
click node_extraction_service "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/knowledge-extraction/extraction-service.ts"
click node_adaptive_engine "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/adaptive-learning/adaptive-engine.ts"
click node_sm2_engine "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/spaced-repetition/sm2-engine.ts"
click node_db "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/data/db/dexie-db.ts"
click node_models "https://github.com/lucianomaciel10/crear-cuestionarios/tree/main/src/data/models"
click node_ai_api "https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/api/extract-concepts.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_main,node_app,node_routes,node_layout,node_dashboard,node_materials,node_flashcards,node_quizzes,node_quiz_player,node_stats,node_subjects_hook,node_materials_hook,node_quiz_hook toneBlue
class node_subject_service,node_material_service,node_knowledge_service,node_question_service,node_flashcard_service,node_material_parser,node_extraction_service,node_adaptive_engine,node_sm2_engine toneAmber
class node_db,node_models,node_ai_api toneMint
```

## Components

### Presentation

React pages, layout, and reusable UI

- [main.tsx](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/main.tsx): boot · App entrypoint · `src/main.tsx`
- [App](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/App.tsx): shell · Top-level app composition · `src/App.tsx`
- [Router](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/routes/index.tsx): routing · SPA route map · `src/routes/index.tsx`
- [Main layout](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/components/layout/MainLayout.tsx): layout · Persistent navigation shell · `src/components/layout/MainLayout.tsx`
- [Dashboard](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/Dashboard.tsx): page · Learning overview · `src/pages/Dashboard.tsx`
- [Materials](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/MaterialsPage.tsx): page · Content management screen · `src/pages/MaterialsPage.tsx`
- [Flashcards](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/Flashcards.tsx): page · Review screen · `src/pages/Flashcards.tsx`
- [Quizzes](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/QuizManagement.tsx): page · Quiz management screen · `src/pages/QuizManagement.tsx`
- [Quiz player](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/QuizPlayer.tsx): page · Quiz taking screen · `src/pages/QuizPlayer.tsx`
- [Statistics](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/pages/Statistics.tsx): page · Progress analytics screen · `src/pages/Statistics.tsx`
- [useSubjects](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useSubjects.ts): hook · Subject state boundary · `src/hooks/useSubjects.ts`
- [useMaterials](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useMaterials.ts): hook · Material state boundary · `src/hooks/useMaterials.ts`
- [useQuizEngine](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/hooks/useQuizEngine.ts): hook · Quiz flow boundary · `src/hooks/useQuizEngine.ts`

### Domain Services

Core learning workflows and business logic

- [Subject service](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/subject.service.ts): service · Subject CRUD and coordination · `src/services/subject.service.ts`
- [Material service](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/material.service.ts): service · Material lifecycle management · `src/services/material.service.ts`
- [Knowledge nodes](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/knowledge-node.service.ts): service · Concept and node management · `src/services/knowledge-node.service.ts`
- [Question service](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/question.service.ts): service · Question generation and retrieval · `src/services/question.service.ts`
- [Flashcard service](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/flashcard.service.ts): service · Flashcard and review operations · `src/services/flashcard.service.ts`
- [Material parser](https://github.com/lucianomaciel10/crear-cuestionarios/tree/main/src/services/material-parser): pipeline · Formats content into normalized text · `src/services/material-parser`
- [Extraction service](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/knowledge-extraction/extraction-service.ts): pipeline · Concept extraction orchestration · `src/services/knowledge-extraction/extraction-service.ts`
- [Adaptive engine](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/adaptive-learning/adaptive-engine.ts): learning · Personalized review selection · `src/services/adaptive-learning/adaptive-engine.ts`
- [SM-2 engine](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/services/spaced-repetition/sm2-engine.ts): scheduler · Spaced repetition scheduling · `src/services/spaced-repetition/sm2-engine.ts`

### Data & Infra

Local persistence, models, and external boundaries

- [Dexie DB](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/src/data/db/dexie-db.ts): indexeddb · Local persistent store · `src/data/db/dexie-db.ts`
- [Domain models](https://github.com/lucianomaciel10/crear-cuestionarios/tree/main/src/data/models): schema · Entity definitions · `src/data/models`
- [Concept API](https://github.com/lucianomaciel10/crear-cuestionarios/blob/main/api/extract-concepts.ts): serverless · Optional concept extraction endpoint · `api/extract-concepts.ts`

## Connections

- main.tsx → App: boots · App entrypoint renders the shell
- App → Router: navigates · Top-level composition includes routing
- Router → Main layout: wraps · Routes are rendered inside the layout
- Router → Dashboard: loads · Primary overview page
- Router → Materials: loads · Materials workflow page
- Router → Flashcards: loads · Flashcard workflow page
- Router → Quizzes: loads · Quiz management page
- Router → Quiz player: loads · Quiz playing page
- Router → Statistics: loads · Statistics page
- Dashboard → useSubjects: reads · Overview uses subject state
- Materials → useMaterials: reads · Material screen uses material state
- Flashcards → useQuizEngine: drives · Review flow uses quiz progression
- Quizzes → useQuizEngine: drives · Quiz management uses quiz state
- Quiz player → useQuizEngine: drives · Quiz play uses progression engine
- useSubjects → Subject service: calls · Hook delegates to subject logic
- useMaterials → Material service: calls · Hook delegates to material logic
- useQuizEngine → Question service: uses · Quiz flow consumes questions
- useQuizEngine → Flashcard service: uses · Quiz flow can surface flashcard reviews
- Subject service → Dexie DB: persists · Subjects are stored locally
- Material service → Dexie DB: persists · Materials are stored locally
- Material service → Material parser: ingests · Raw files are normalized before storage
- Material service → Knowledge nodes: derives · Materials feed knowledge nodes
- Knowledge nodes → Extraction service: extracts · Concept extraction pipeline produces nodes
- Extraction service → Concept API: optionally calls · AI-backed extraction can cross serverless boundary
- Knowledge nodes → SM-2 engine: updates · Mastery state informs scheduling
- SM-2 engine → Adaptive engine: feeds · Spacing results inform adaptation
- Question service → Knowledge nodes: builds from · Questions are derived from knowledge nodes
- Flashcard service → Knowledge nodes: tracks · Flashcards relate to node mastery
- Knowledge nodes → Domain models: uses · Domain entities define knowledge structures
- Subject service → Domain models: uses · Subject entities define persistence shape
- Material service → Domain models: uses · Material entities define persistence shape
- Question service → Domain models: uses · Question entities define storage shape
