How enzofarai/vulanet works
1. Overall shape
- This repository is a static, content-driven learning app: HTML entry pages plus client-side JavaScript that assembles reusable UI parts, renders lesson/course content, and runs quizzes.
- The main architectural boundary is between source fragments in src/, content/data in data/, and served pages/assets in the root and public/.
2. Entry points and navigation pages
- The top-level HTML files (index.html, onboarding.html, courses.html, 404.html) are the main navigation and landing surfaces.
- pages/registration.html, pages/loading.html, and pages/registration-completion.html suggest a flow around account/setup or onboarding before learning begins.
3. Lesson delivery layer
- pages/lesson.html is the generic lesson shell.
- Specific lesson pages exist under src/pages/lessons/... and pages/lessons/..., indicating lesson content is organized per course and topic, then rendered through shared layout/logic.
- This separation implies a template + content model rather than a single monolithic app page.
4. Course and lesson content model
- Course metadata lives in data/courses/*.json.
- Lesson-specific content lives in data/lessons/<course>/...json.
- This is the core content boundary: the app UI reads structured JSON to determine what course/lesson to show, rather than hardcoding content into the UI.
5. Did-you-know / supplemental content subsystem
- data/dyk/*.html contains subject-specific “DYK” pages for biology, business, chemistry, computer science, engineering, general, humanities, law, mathematics, medicine, and physics.
- src/js/dyk-map.js likely maps subject/course context to one of these supplemental content pages.
6. Learning-path and course mapping logic
- src/js/course-data.js and src/js/course-path.js are the data/logic layer that connects raw course content to the learning path UI.
- src/styles/learning-path.css suggests a dedicated visual subsystem for progression through a course, distinct from lesson playback.
7. Quiz and reward engine
- src/js/quiz-engine.js is the central interaction engine for lesson quizzes.
- The presence of reward/feedback modals and sounds indicates the quiz flow drives outcomes like correctness, streaks, coins, hearts, completion, and review.
- This is likely the main stateful client-side subsystem in the repo.
8. Reusable UI composition
- src/components/header.html and src/components/footer.html are shared layout fragments.
- src/js/load-components.js implies the app loads these fragments dynamically into pages, reducing duplication across the static site.
- Modal fragments under src/components/modals/ are also reused across quiz and learning flows.
9. Modal-driven game mechanics
- The modal set covers most learner state transitions: achievement, streak, coins reward, boost reward, heart loss/refill, daily quest, lesson complete, quit confirmation, record, and review questions.
- This suggests the app behaves like a gamified learning product, with UI state changes surfaced through modal overlays rather than separate pages.
10. Assets and presentation layer
- public/assets/ contains the production assets: audio feedback, fonts, icons, images, country assets, course assets, and Lottie animations.
- Audio files such as correct/incorrect, hearts, streak, and completion sounds are tightly coupled to quiz/reward interactions.
- The fonts/icons/images under public/ are part of the runtime presentation bundle, not source templates.
11. External service boundary
- src/js/supabase.js indicates an integration layer for Supabase.
- Even without implementation details, this is the clear boundary for backend-like concerns such as auth, user state, or progress persistence, separate from the static content and UI logic.
12. Styling system
- Styling is split into focused CSS files: src/styles/quiz.css, src/styles/learning-path.css, and component styles like src/styles/components/buttons.css.
- This suggests the UI is organized around a few major interaction surfaces rather than a single global stylesheet.
13. Deployment/runtime
- vercel.json indicates deployment on Vercel, which typically means the app is served as a static frontend with routing/config handled at the edge.
- The repo layout fits a static-hosting architecture: pages, components, scripts, and assets are all preorganized for direct serving.
14. Key architectural diagram boundaries
- A useful diagram should show:
- Static entry pages
- Shared component fragments
- Client-side JS orchestration
- Structured course/lesson data
- Modal/reward systems
- Static assets
- Supabase integration boundary
- Deployment on Vercel
Main entry points: quiz-engine.js Quiz engine · header.html Shared UI · introduction-to-nucleic-acids.html Lesson pages · lesson.html Lesson shell
Components 23
Entry & routes
Static entry pages and lesson shells served directly as HTML.
- Home · Primary landing page.
index.html - Courses · Course browsing surface.
courses.html - Onboarding · Setup and introduction page.
onboarding.html - Registration · Registration step in the setup flow.
pages/registration.html - Loading · Intermediate loading screen.
pages/loading.html - Completion · Registration completion screen.
pages/registration-completion.html - Lesson shell · Generic lesson container for rendered content.
pages/lesson.html - Course lessons · Per-course lesson entry pages.
pages/lessons/g12-life-sciences.html
Source layer
Reusable UI fragments and client-side orchestration in src/.
- Shared UI · Reusable header and footer fragments.
src/components/header.html - Component loader · Injects shared fragments into static pages.
src/js/load-components.js - Course data · Course metadata access and normalization.
src/js/course-data.js - Learning path · Builds progression and course path behavior.
src/js/course-path.js - Quiz engine · Core lesson interaction and scoring engine.
src/js/quiz-engine.js - DYK map · Selects supplemental did-you-know content by subject.
src/js/dyk-map.js - Lesson pages · Source lesson pages for specific topics.
src/pages/lessons/g12-life-sciences/introduction-to-nucleic-acids.html - Modals · Gamified feedback and state-transition dialogs.
src/components/modals/lesson-complete.html - Styles · Dedicated styling for quiz and learning path surfaces.
src/styles/quiz.css
Content model
Structured course, lesson, and supplemental learning content.
- Course JSON · Structured course metadata and catalog content.
data/courses/g12-life-sciences.json - Lesson JSON · Structured lesson content for a specific course.
data/lessons/g12-life-sciences/introduction-to-nucleic-acids.json - DYK pages · Subject-specific supplemental learning pages.
data/dyk/biology.html
Runtime assets
Fonts, audio, images, icons, and animations used by the client.
- Assets · Fonts, audio, images, icons, and Lottie animations.
public/assets/fonts/fonts.css
Connections 23
- Home → Shared UI: uses · Home page composes shared layout fragments.
- Courses → Shared UI: uses · Courses page reuses common header/footer.
- Onboarding → Shared UI: uses · Onboarding pages share the same shell.
- Lesson shell → Component loader: loads · Lesson shell injects shared components at runtime.
- Course lessons → Lesson pages: routes to · Course-specific lesson pages point into topic lesson sources.
- Course lessons → Lesson shell: wraps · Per-course pages use the generic lesson shell.
- Component loader → Shared UI: injects · Loads header and footer fragments into pages.
- Course data → Course JSON: reads · Client code consumes course metadata.
- Learning path → Course data: builds on · Learning-path logic depends on course data layer.
- Learning path → Styles: styled by · Path UI has dedicated presentation rules.
- Quiz engine → Modals: opens · Quiz flow presents feedback and state modals.
- Quiz engine → Assets: plays · Quiz engine triggers audio and visual assets.
- Quiz engine → Supabase: syncs · User progress and state can persist through the backend boundary.
- Quiz engine → Lesson JSON: consumes · Quiz questions and lesson structure come from lesson JSON.
- DYK map → DYK pages: maps to · Subject mapping resolves the correct supplemental content.
- Lesson pages → Lesson JSON: renders · Lesson pages are driven by structured lesson content.
- Lesson pages → DYK map: links · Lesson pages can surface related supplemental content.
- Lesson pages → Quiz engine: embeds · Lesson pages host the interactive quiz flow.
- Modals → Assets: uses · Modal feedback relies on audio/animation assets.
- Shared UI → Styles: styled by · Shared fragments rely on component CSS.
- Lesson shell → Styles: styled by · Lesson shell uses quiz and path styling.
- Vercel → Home: serves · Deployment serves the static entry surfaces.
- Vercel → Lesson shell: serves · Deployment serves lesson routes and pages.