# kloud-labs/ekloud architecture

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

- Interactive diagram: https://gitdiagram.com/kloud-labs/ekloud
- Repository: https://github.com/kloud-labs/ekloud

## Overview

1. **Overall shape**
   - Ekloud is a **React + TypeScript learning platform** with a **route-driven frontend** under `src/app`, backed by **Supabase** for auth/data and a small **Supabase Edge Function** for AI access.
   - The product is organized around three big areas: **public marketing**, **authenticated learner experience**, and a **full admin back office**.

2. **Frontend application shell**
   - Global app entry points live in `src/main.tsx`, `src/App.tsx`, and `src/app/globals.css`.
   - The UI is built from reusable components in `src/components`, with shared styling via Tailwind/PostCSS and custom fonts in `src/fonts`.
   - Public SEO assets are included via `public/robots.txt` and `public/sitemap.xml`.

3. **Routing and page boundaries**
   - `src/app` contains the major user-facing routes:
     - public pages like landing, courses, terms, support, login/signup
     - authenticated learner areas like dashboard, lessons, modules, quizzes, exam, friends, leaderboard, settings
     - profile pages under `src/app/u/[username]`
     - admin pages under `src/app/admin`
   - This is a **screen-first architecture**: most features are separated by route, with each page composing domain-specific components.

4. **Authentication and session flow**
   - Authentication is centered on `src/contexts/AuthContext.tsx`, `src/hooks/useAuth.tsx`, and `src/components/ProtectedRoute.tsx`.
   - The auth flow includes dedicated login/signup screens and a Supabase callback route at `src/app/auth/callback/page.tsx`.
   - The `src/lib/supabase.ts` module is the main integration point for session and backend access.

5. **Learning content subsystem**
   - The core educational content is split into **courses, modules, lessons, quizzes, and exams**.
   - Routes like `src/app/courses`, `src/app/modules/[id]`, `src/app/lessons/[id]`, `src/app/quiz/[id]`, and `src/app/exam/[id]` indicate a hierarchical learning path.
   - Supporting utilities in `src/lib/layouts.ts` and `src/lib/shortcodes.ts` suggest content rendering/templating for lesson pages.

6. **Assessment and progression**
   - Assessment is handled through quiz and exam pages, plus supporting UI such as `InlineQuiz` and `SkillTree`.
   - `src/lib/gamification.ts` and the leaderboard route indicate points/progress/streak-style mechanics.
   - The app appears designed to turn learning activity into visible progression rather than simple static reading.

7. **Community and competition features**
   - Social and competitive features are first-class: `friends`, `leaderboard`, `clan-quiz/weekly`, and `clan-quiz/monthly`.
   - User profile pages under `u/[username]` and the account/settings area suggest a persistent identity layer around the learner.
   - These features likely share the same Supabase-backed user/profile data as the learning flow.

8. **Admin back office**
   - `src/app/admin` is a separate management surface for content and users.
   - It includes CRUD flows for **lessons, modules, quizzes, and skills**, plus dedicated components for **user management** and **skill management**.
   - Admin pages are split into create/edit/detail routes, which makes the content model explicit and easy to diagram.

9. **AI/assistant subsystem**
   - `src/components/KloudyAssistant.tsx`, `TypingMessage.tsx`, `Typewriter.tsx`, and `InlineQuiz.tsx` point to conversational and guided-learning UX.
   - The backend side is isolated in `supabase/functions/ai-proxy/index.ts`, which likely protects AI provider credentials and centralizes request handling.
   - `src/lib/ai-balancer.ts` suggests client-side logic for routing or balancing AI requests across providers/models.

10. **Infrastructure and deployment**
   - The repo is configured for **Vercel deployment** (`vercel.json`) and uses a **Supabase backend** (`supabase/`).
   - `supabase/functions/deno.json` shows the AI proxy runs in the Supabase/Deno serverless environment.
   - `.github/workflows/update-portfolio-stats.yml` adds lightweight automation, but the main runtime boundary is still frontend + Supabase.

11. **What to show in an architecture diagram**
   - Draw the frontend as one large client application with three lanes: **public pages**, **learner experience**, and **admin experience**.
   - Put **Supabase** as the central backend for auth/data, with the **AI proxy function** as a separate serverless boundary.
   - Show shared cross-cutting modules beneath the app: **auth context**, **gamification**, **AI utilities**, **content rendering helpers**, and **UI components**.

Main entry points: [`src/App.tsx`](https://github.com/kloud-labs/ekloud/blob/main/src/App.tsx) (App shell), [`src/lib/supabase.ts`](https://github.com/kloud-labs/ekloud/blob/main/src/lib/supabase.ts) (Supabase client), [`src/app/dashboard/page.tsx`](https://github.com/kloud-labs/ekloud/blob/main/src/app/dashboard/page.tsx) (Learner area), [`src/components/Navbar.tsx`](https://github.com/kloud-labs/ekloud/blob/main/src/components/Navbar.tsx) (UI components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_src_main(("Main entry<br/>app bootstrap<br/>[main.tsx]"))
  node_src_app_shell["App shell<br/>root router<br/>[App.tsx]"]
  node_src_public_routes["Public pages<br/>marketing routes<br/>[page.tsx]"]
  node_src_learner_routes["Learner area<br/>student routes<br/>[page.tsx]"]
  node_src_admin_routes["Admin back office<br/>admin routes<br/>[page.tsx]"]
  node_src_auth_routes["Auth flow<br/>login callback<br/>[page.tsx]"]
  node_src_lesson_routes["Learning path<br/>content routes<br/>[page.tsx]"]
  node_src_social_routes["Community features<br/>social routes<br/>[page.tsx]"]
end

subgraph group_backend["Backend"]
  node_src_supabase_client[("Supabase client<br/>backend gateway<br/>[supabase.ts]")]
  node_supabase_ai_proxy["AI proxy<br/>edge function<br/>[index.ts]"]
end

subgraph group_shared["Shared modules"]
  node_src_ui_components["UI components<br/>shared UI<br/>[Navbar.tsx]"]
  node_src_auth_context["Auth context<br/>session state<br/>[AuthContext.tsx]"]
  node_src_theme_context["Theme context<br/>ui state<br/>[ThemeContext.tsx]"]
  node_src_auth_hook["Auth hook<br/>auth helper<br/>[useAuth.tsx]"]
  node_src_content_helpers["Content helpers<br/>rendering utils<br/>[layouts.ts]"]
  node_src_gamification["Gamification<br/>progress system<br/>[gamification.ts]"]
  node_src_ai_balancer["AI balancer<br/>ai routing<br/>[ai-balancer.ts]"]
  node_src_public_shell["Public UI<br/>landing UI<br/>[Hero.tsx]"]
end

subgraph group_ops["Ops"]
end

node_src_main -->|"boots"| node_src_app_shell
node_src_app_shell -->|"routes"| node_src_public_routes
node_src_app_shell -->|"routes"| node_src_learner_routes
node_src_app_shell -->|"routes"| node_src_admin_routes
node_src_app_shell -->|"routes"| node_src_auth_routes
node_src_app_shell -->|"composes"| node_src_ui_components
node_src_public_routes -->|"uses"| node_src_public_shell
node_src_learner_routes -->|"renders"| node_src_content_helpers
node_src_learner_routes -->|"awards"| node_src_gamification
node_src_learner_routes -->|"loads"| node_src_supabase_client
node_src_social_routes -->|"uses"| node_src_gamification
node_src_social_routes -->|"syncs"| node_src_supabase_client
node_src_admin_routes -->|"manages"| node_src_supabase_client
node_src_auth_routes -->|"updates"| node_src_auth_context
node_src_auth_context -->|"exposes"| node_src_auth_hook
node_src_auth_context -->|"authenticates"| node_src_supabase_client
node_src_ui_components -->|"guides"| node_src_ai_balancer
node_src_ui_components -->|"calls"| node_supabase_ai_proxy
node_supabase_ai_proxy -.->|"integrates"| node_src_supabase_client

click node_src_main "https://github.com/kloud-labs/ekloud/blob/main/src/main.tsx"
click node_src_app_shell "https://github.com/kloud-labs/ekloud/blob/main/src/App.tsx"
click node_src_public_routes "https://github.com/kloud-labs/ekloud/blob/main/src/app/page.tsx"
click node_src_learner_routes "https://github.com/kloud-labs/ekloud/blob/main/src/app/dashboard/page.tsx"
click node_src_admin_routes "https://github.com/kloud-labs/ekloud/blob/main/src/app/admin/page.tsx"
click node_src_auth_routes "https://github.com/kloud-labs/ekloud/blob/main/src/app/auth/callback/page.tsx"
click node_src_ui_components "https://github.com/kloud-labs/ekloud/blob/main/src/components/Navbar.tsx"
click node_src_auth_context "https://github.com/kloud-labs/ekloud/blob/main/src/contexts/AuthContext.tsx"
click node_src_theme_context "https://github.com/kloud-labs/ekloud/blob/main/src/contexts/ThemeContext.tsx"
click node_src_auth_hook "https://github.com/kloud-labs/ekloud/blob/main/src/hooks/useAuth.tsx"
click node_src_content_helpers "https://github.com/kloud-labs/ekloud/blob/main/src/lib/layouts.ts"
click node_src_gamification "https://github.com/kloud-labs/ekloud/blob/main/src/lib/gamification.ts"
click node_src_ai_balancer "https://github.com/kloud-labs/ekloud/blob/main/src/lib/ai-balancer.ts"
click node_src_supabase_client "https://github.com/kloud-labs/ekloud/blob/main/src/lib/supabase.ts"
click node_supabase_ai_proxy "https://github.com/kloud-labs/ekloud/blob/main/supabase/functions/ai-proxy/index.ts"
click node_src_lesson_routes "https://github.com/kloud-labs/ekloud/blob/main/src/app/courses/page.tsx"
click node_src_social_routes "https://github.com/kloud-labs/ekloud/blob/main/src/app/clan-quiz/page.tsx"
click node_src_public_shell "https://github.com/kloud-labs/ekloud/blob/main/src/components/Hero.tsx"

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_src_main,node_src_app_shell,node_src_public_routes,node_src_learner_routes,node_src_admin_routes,node_src_auth_routes,node_src_lesson_routes,node_src_social_routes toneBlue
class node_src_supabase_client,node_supabase_ai_proxy toneAmber
class node_src_ui_components,node_src_auth_context,node_src_theme_context,node_src_auth_hook,node_src_content_helpers,node_src_gamification,node_src_ai_balancer,node_src_public_shell toneMint
```

## Components

### Client app

React/TypeScript frontend with routed learner, public, and admin screens.

- [Main entry](https://github.com/kloud-labs/ekloud/blob/main/src/main.tsx): app bootstrap · Vite entry that mounts the application. · `src/main.tsx`
- [App shell](https://github.com/kloud-labs/ekloud/blob/main/src/App.tsx): root router · Top-level app composition and route wiring. · `src/App.tsx`
- [Public pages](https://github.com/kloud-labs/ekloud/blob/main/src/app/page.tsx): marketing routes · Landing, courses, terms, support, login, signup, and credits screens. · `src/app/page.tsx`
- [Learner area](https://github.com/kloud-labs/ekloud/blob/main/src/app/dashboard/page.tsx): student routes · Dashboard, lessons, modules, quizzes, exams, friends, leaderboard, settings, account, and profiles. · `src/app/dashboard/page.tsx`
- [Admin back office](https://github.com/kloud-labs/ekloud/blob/main/src/app/admin/page.tsx): admin routes · Management surface for lessons, modules, quizzes, skills, and users. · `src/app/admin/page.tsx`
- [Auth flow](https://github.com/kloud-labs/ekloud/blob/main/src/app/auth/callback/page.tsx): login callback · Login, signup, and Supabase auth callback handling. · `src/app/auth/callback/page.tsx`
- [Learning path](https://github.com/kloud-labs/ekloud/blob/main/src/app/courses/page.tsx): content routes · Course, module, lesson, quiz, and exam screens that drive the core study flow. · `src/app/courses/page.tsx`
- [Community features](https://github.com/kloud-labs/ekloud/blob/main/src/app/clan-quiz/page.tsx): social routes · Clan quizzes, friends, and leaderboard screens around identity and competition. · `src/app/clan-quiz/page.tsx`

### Backend

Supabase-backed auth/data and serverless AI proxy.

- [Supabase client](https://github.com/kloud-labs/ekloud/blob/main/src/lib/supabase.ts): backend gateway · Primary browser integration point for auth and data access. · `src/lib/supabase.ts`
- [AI proxy](https://github.com/kloud-labs/ekloud/blob/main/supabase/functions/ai-proxy/index.ts): edge function · Serverless boundary that protects AI credentials and centralizes proxying. · `supabase/functions/ai-proxy/index.ts`

### Shared modules

Cross-cutting UI, auth, content, and game mechanics.

- [UI components](https://github.com/kloud-labs/ekloud/blob/main/src/components/Navbar.tsx): shared UI · Reusable interface pieces like navbar, hero, assistant, quizzes, skill tree, and auth UI. · `src/components/Navbar.tsx`
- [Auth context](https://github.com/kloud-labs/ekloud/blob/main/src/contexts/AuthContext.tsx): session state · Client auth/session state and guards. · `src/contexts/AuthContext.tsx`
- [Theme context](https://github.com/kloud-labs/ekloud/blob/main/src/contexts/ThemeContext.tsx): ui state · Application theme state. · `src/contexts/ThemeContext.tsx`
- [Auth hook](https://github.com/kloud-labs/ekloud/blob/main/src/hooks/useAuth.tsx): auth helper · Hook for consuming auth state. · `src/hooks/useAuth.tsx`
- [Content helpers](https://github.com/kloud-labs/ekloud/blob/main/src/lib/layouts.ts): rendering utils · Layout and shortcode helpers for lesson and content rendering. · `src/lib/layouts.ts`
- [Gamification](https://github.com/kloud-labs/ekloud/blob/main/src/lib/gamification.ts): progress system · Points, streaks, and progression mechanics used by learner-facing features. · `src/lib/gamification.ts`
- [AI balancer](https://github.com/kloud-labs/ekloud/blob/main/src/lib/ai-balancer.ts): ai routing · Client-side AI request selection and balancing logic. · `src/lib/ai-balancer.ts`
- [Public UI](https://github.com/kloud-labs/ekloud/blob/main/src/components/Hero.tsx): landing UI · Hero, features, and navigation for the marketing experience. · `src/components/Hero.tsx`

## Connections

- Main entry → App shell: boots · Application entry mounts the routed app.
- App shell → Public pages: routes · Shell renders public marketing and auth screens.
- App shell → Learner area: routes · Shell renders learner-facing pages.
- App shell → Admin back office: routes · Shell renders admin back office pages.
- App shell → Auth flow: routes · Shell includes the login, signup, and callback flow.
- App shell → UI components: composes · App shell is built from shared UI components.
- Public pages → Public UI: uses · Public pages rely on hero and feature components.
- Learner area → Content helpers: renders · Learning screens use layout and shortcode helpers.
- Learner area → Gamification: awards · Progress and competition features feed learner progression.
- Learner area → Supabase client: loads · Learner data and sessions come from Supabase.
- Community features → Gamification: uses · Community and competition pages surface progression mechanics.
- Community features → Supabase client: syncs · Social features share backend user/profile data.
- Admin back office → Supabase client: manages · Admin CRUD flows operate on Supabase-backed content and users.
- Auth flow → Auth context: updates · Auth callback and login flow establish session state.
- Auth context → Auth hook: exposes · Auth state is consumed through a helper hook.
- Auth context → Supabase client: authenticates · Session management is centered on Supabase.
- UI components → AI balancer: guides · Assistant and quiz components use AI routing logic.
- UI components → AI proxy: calls · Assistant UX reaches the AI proxy boundary for model access.
- AI proxy → Supabase client: integrates · Backend edge function fits the same Supabase platform boundary.