# enzofarai/vulanet architecture

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

- Interactive diagram: https://gitdiagram.com/enzofarai/vulanet
- Repository: https://github.com/enzofarai/vulanet

## Overview

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: [`src/js/quiz-engine.js`](https://github.com/enzofarai/vulanet/blob/main/src/js/quiz-engine.js) (Quiz engine), [`src/components/header.html`](https://github.com/enzofarai/vulanet/blob/main/src/components/header.html) (Shared UI), [`src/pages/lessons/g12-life-sciences/introduction-to-nucleic-acids.html`](https://github.com/enzofarai/vulanet/blob/main/src/pages/lessons/g12-life-sciences/introduction-to-nucleic-acids.html) (Lesson pages), [`pages/lesson.html`](https://github.com/enzofarai/vulanet/blob/main/pages/lesson.html) (Lesson shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & routes"]
  node_index["Home<br/>html entry<br/>[index.html]"]
  node_courses["Courses<br/>html entry<br/>[courses.html]"]
  node_onboarding["Onboarding<br/>html flow<br/>[onboarding.html]"]
  node_reg["Registration<br/>html flow<br/>[registration.html]"]
  node_loading["Loading<br/>html flow<br/>[loading.html]"]
  node_regdone["Completion<br/>html flow"]
  node_lessonpage["Lesson shell<br/>html shell<br/>[lesson.html]"]
  node_coursepages["Course lessons<br/>html pages"]
end

subgraph group_source["Source layer"]
  node_sharedui["Shared UI<br/>fragments<br/>[header.html]"]
  node_componentloader["Component loader<br/>client loader<br/>[load-components.js]"]
  node_coursejs["Course data<br/>client data<br/>[course-data.js]"]
  node_pathjs["Learning path<br/>client flow<br/>[course-path.js]"]
  node_quiz["Quiz engine<br/>client engine<br/>[quiz-engine.js]"]
  node_dymap["DYK map<br/>client mapping<br/>[dyk-map.js]"]
  node_lessonsrc["Lesson pages<br/>lesson templates"]
  node_modalset["Modals<br/>ui overlays"]
  node_styles["Styles<br/>css system<br/>[quiz.css]"]
end

subgraph group_content["Content model"]
  node_coursesdata["Course JSON<br/>course data"]
  node_lessonsdata["Lesson JSON<br/>lesson content"]
  node_dykcontent["DYK pages<br/>supplemental html<br/>[biology.html]"]
end

subgraph group_assets["Runtime assets"]
  node_assets["Assets<br/>[fonts.css]"]
end

subgraph group_platform["Platform boundary"]
  node_supabase["Supabase<br/>integration<br/>[supabase.js]"]
  node_vercel["Vercel<br/>deployment<br/>[vercel.json]"]
end

node_index -->|"uses"| node_sharedui
node_courses -->|"uses"| node_sharedui
node_onboarding -->|"uses"| node_sharedui
node_lessonpage -->|"loads"| node_componentloader
node_coursepages -->|"routes to"| node_lessonsrc
node_coursepages -->|"wraps"| node_lessonpage
node_componentloader -->|"injects"| node_sharedui
node_coursejs -->|"reads"| node_coursesdata
node_pathjs -->|"builds on"| node_coursejs
node_pathjs -->|"styled by"| node_styles
node_quiz -->|"opens"| node_modalset
node_quiz -->|"plays"| node_assets
node_quiz -->|"syncs"| node_supabase
node_quiz -->|"consumes"| node_lessonsdata
node_dymap -->|"maps to"| node_dykcontent
node_lessonsrc -->|"renders"| node_lessonsdata
node_lessonsrc -->|"links"| node_dymap
node_lessonsrc -->|"embeds"| node_quiz
node_modalset -->|"uses"| node_assets
node_sharedui -->|"styled by"| node_styles
node_lessonpage -->|"styled by"| node_styles
node_vercel -->|"serves"| node_index
node_vercel -->|"serves"| node_lessonpage

click node_index "https://github.com/enzofarai/vulanet/blob/main/index.html"
click node_courses "https://github.com/enzofarai/vulanet/blob/main/courses.html"
click node_onboarding "https://github.com/enzofarai/vulanet/blob/main/onboarding.html"
click node_reg "https://github.com/enzofarai/vulanet/blob/main/pages/registration.html"
click node_loading "https://github.com/enzofarai/vulanet/blob/main/pages/loading.html"
click node_regdone "https://github.com/enzofarai/vulanet/blob/main/pages/registration-completion.html"
click node_lessonpage "https://github.com/enzofarai/vulanet/blob/main/pages/lesson.html"
click node_coursepages "https://github.com/enzofarai/vulanet/blob/main/pages/lessons/g12-life-sciences.html"
click node_sharedui "https://github.com/enzofarai/vulanet/blob/main/src/components/header.html"
click node_componentloader "https://github.com/enzofarai/vulanet/blob/main/src/js/load-components.js"
click node_coursejs "https://github.com/enzofarai/vulanet/blob/main/src/js/course-data.js"
click node_pathjs "https://github.com/enzofarai/vulanet/blob/main/src/js/course-path.js"
click node_quiz "https://github.com/enzofarai/vulanet/blob/main/src/js/quiz-engine.js"
click node_dymap "https://github.com/enzofarai/vulanet/blob/main/src/js/dyk-map.js"
click node_supabase "https://github.com/enzofarai/vulanet/blob/main/src/js/supabase.js"
click node_coursesdata "https://github.com/enzofarai/vulanet/blob/main/data/courses/g12-life-sciences.json"
click node_lessonsdata "https://github.com/enzofarai/vulanet/blob/main/data/lessons/g12-life-sciences/introduction-to-nucleic-acids.json"
click node_dykcontent "https://github.com/enzofarai/vulanet/blob/main/data/dyk/biology.html"
click node_lessonsrc "https://github.com/enzofarai/vulanet/blob/main/src/pages/lessons/g12-life-sciences/introduction-to-nucleic-acids.html"
click node_modalset "https://github.com/enzofarai/vulanet/blob/main/src/components/modals/lesson-complete.html"
click node_styles "https://github.com/enzofarai/vulanet/blob/main/src/styles/quiz.css"
click node_assets "https://github.com/enzofarai/vulanet/blob/main/public/assets/fonts/fonts.css"
click node_vercel "https://github.com/enzofarai/vulanet/blob/main/vercel.json"

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_index,node_courses,node_onboarding,node_reg,node_loading,node_regdone,node_lessonpage,node_coursepages toneBlue
class node_sharedui,node_componentloader,node_coursejs,node_pathjs,node_quiz,node_dymap,node_lessonsrc,node_modalset,node_styles toneAmber
class node_coursesdata,node_lessonsdata,node_dykcontent toneMint
class node_assets toneRose
class node_supabase,node_vercel toneIndigo
```

## Components

### Entry & routes

Static entry pages and lesson shells served directly as HTML.

- [Home](https://github.com/enzofarai/vulanet/blob/main/index.html): html entry · Primary landing page. · `index.html`
- [Courses](https://github.com/enzofarai/vulanet/blob/main/courses.html): html entry · Course browsing surface. · `courses.html`
- [Onboarding](https://github.com/enzofarai/vulanet/blob/main/onboarding.html): html flow · Setup and introduction page. · `onboarding.html`
- [Registration](https://github.com/enzofarai/vulanet/blob/main/pages/registration.html): html flow · Registration step in the setup flow. · `pages/registration.html`
- [Loading](https://github.com/enzofarai/vulanet/blob/main/pages/loading.html): html flow · Intermediate loading screen. · `pages/loading.html`
- [Completion](https://github.com/enzofarai/vulanet/blob/main/pages/registration-completion.html): html flow · Registration completion screen. · `pages/registration-completion.html`
- [Lesson shell](https://github.com/enzofarai/vulanet/blob/main/pages/lesson.html): html shell · Generic lesson container for rendered content. · `pages/lesson.html`
- [Course lessons](https://github.com/enzofarai/vulanet/blob/main/pages/lessons/g12-life-sciences.html): html pages · Per-course lesson entry pages. · `pages/lessons/g12-life-sciences.html`

### Source layer

Reusable UI fragments and client-side orchestration in src/.

- [Shared UI](https://github.com/enzofarai/vulanet/blob/main/src/components/header.html): fragments · Reusable header and footer fragments. · `src/components/header.html`
- [Component loader](https://github.com/enzofarai/vulanet/blob/main/src/js/load-components.js): client loader · Injects shared fragments into static pages. · `src/js/load-components.js`
- [Course data](https://github.com/enzofarai/vulanet/blob/main/src/js/course-data.js): client data · Course metadata access and normalization. · `src/js/course-data.js`
- [Learning path](https://github.com/enzofarai/vulanet/blob/main/src/js/course-path.js): client flow · Builds progression and course path behavior. · `src/js/course-path.js`
- [Quiz engine](https://github.com/enzofarai/vulanet/blob/main/src/js/quiz-engine.js): client engine · Core lesson interaction and scoring engine. · `src/js/quiz-engine.js`
- [DYK map](https://github.com/enzofarai/vulanet/blob/main/src/js/dyk-map.js): client mapping · Selects supplemental did-you-know content by subject. · `src/js/dyk-map.js`
- [Lesson pages](https://github.com/enzofarai/vulanet/blob/main/src/pages/lessons/g12-life-sciences/introduction-to-nucleic-acids.html): lesson templates · Source lesson pages for specific topics. · `src/pages/lessons/g12-life-sciences/introduction-to-nucleic-acids.html`
- [Modals](https://github.com/enzofarai/vulanet/blob/main/src/components/modals/lesson-complete.html): ui overlays · Gamified feedback and state-transition dialogs. · `src/components/modals/lesson-complete.html`
- [Styles](https://github.com/enzofarai/vulanet/blob/main/src/styles/quiz.css): css system · Dedicated styling for quiz and learning path surfaces. · `src/styles/quiz.css`

### Content model

Structured course, lesson, and supplemental learning content.

- [Course JSON](https://github.com/enzofarai/vulanet/blob/main/data/courses/g12-life-sciences.json): course data · Structured course metadata and catalog content. · `data/courses/g12-life-sciences.json`
- [Lesson JSON](https://github.com/enzofarai/vulanet/blob/main/data/lessons/g12-life-sciences/introduction-to-nucleic-acids.json): lesson content · Structured lesson content for a specific course. · `data/lessons/g12-life-sciences/introduction-to-nucleic-acids.json`
- [DYK pages](https://github.com/enzofarai/vulanet/blob/main/data/dyk/biology.html): supplemental html · Subject-specific supplemental learning pages. · `data/dyk/biology.html`

### Runtime assets

Fonts, audio, images, icons, and animations used by the client.

- [Assets](https://github.com/enzofarai/vulanet/blob/main/public/assets/fonts/fonts.css): runtime assets · Fonts, audio, images, icons, and Lottie animations. · `public/assets/fonts/fonts.css`

### Platform boundary

External services and deployment/runtime configuration.

- [Supabase](https://github.com/enzofarai/vulanet/blob/main/src/js/supabase.js): integration · Backend/service boundary for persistence and user state. · `src/js/supabase.js`
- [Vercel](https://github.com/enzofarai/vulanet/blob/main/vercel.json): deployment · Static hosting and deployment configuration. · `vercel.json`

## Connections

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