How lucianomaciel10/crear-cuestionarios works
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: index.tsx Router · knowledge-node.service.ts Knowledge nodes · material.service.ts Material service · useQuizEngine.ts useQuizEngine
Components 25
Presentation
React pages, layout, and reusable UI
- main.tsx · App entrypoint
src/main.tsx - App · Top-level app composition
src/App.tsx - Router · SPA route map
src/routes/index.tsx - Main layout · Persistent navigation shell
src/components/layout/MainLayout.tsx - Dashboard · Learning overview
src/pages/Dashboard.tsx - Materials · Content management screen
src/pages/MaterialsPage.tsx - Flashcards · Review screen
src/pages/Flashcards.tsx - Quizzes · Quiz management screen
src/pages/QuizManagement.tsx - Quiz player · Quiz taking screen
src/pages/QuizPlayer.tsx - Statistics · Progress analytics screen
src/pages/Statistics.tsx - useSubjects · Subject state boundary
src/hooks/useSubjects.ts - useMaterials · Material state boundary
src/hooks/useMaterials.ts - useQuizEngine · Quiz flow boundary
src/hooks/useQuizEngine.ts
Domain Services
Core learning workflows and business logic
- Subject service · Subject CRUD and coordination
src/services/subject.service.ts - Material service · Material lifecycle management
src/services/material.service.ts - Knowledge nodes · Concept and node management
src/services/knowledge-node.service.ts - Question service · Question generation and retrieval
src/services/question.service.ts - Flashcard service · Flashcard and review operations
src/services/flashcard.service.ts - Material parser · Formats content into normalized text
src/services/material-parser - Extraction service · Concept extraction orchestration
src/services/knowledge-extraction/extraction-service.ts - Adaptive engine · Personalized review selection
src/services/adaptive-learning/adaptive-engine.ts - SM-2 engine · Spaced repetition scheduling
src/services/spaced-repetition/sm2-engine.ts
Data & Infra
Local persistence, models, and external boundaries
- Dexie DB · Local persistent store
src/data/db/dexie-db.ts - Domain models · Entity definitions
src/data/models - Concept API · Optional concept extraction endpoint
api/extract-concepts.ts
Connections 32
- 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