How kloud-labs/ekloud works
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: App.tsx App shell · supabase.ts Supabase client · page.tsx Learner area · Navbar.tsx UI components
Components 18
Client app
React/TypeScript frontend with routed learner, public, and admin screens.
- Main entry · Vite entry that mounts the application.
src/main.tsx - App shell · Top-level app composition and route wiring.
src/App.tsx - Public pages · Landing, courses, terms, support, login, signup, and credits screens.
src/app/page.tsx - Learner area · Dashboard, lessons, modules, quizzes, exams, friends, leaderboard, settings, account, and profiles.
src/app/dashboard/page.tsx - Admin back office · Management surface for lessons, modules, quizzes, skills, and users.
src/app/admin/page.tsx - Auth flow · Login, signup, and Supabase auth callback handling.
src/app/auth/callback/page.tsx - Learning path · Course, module, lesson, quiz, and exam screens that drive the core study flow.
src/app/courses/page.tsx - Community features · 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 · Primary browser integration point for auth and data access.
src/lib/supabase.ts - AI proxy · 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 · Reusable interface pieces like navbar, hero, assistant, quizzes, skill tree, and auth UI.
src/components/Navbar.tsx - Auth context · Client auth/session state and guards.
src/contexts/AuthContext.tsx - Theme context · Application theme state.
src/contexts/ThemeContext.tsx - Auth hook · Hook for consuming auth state.
src/hooks/useAuth.tsx - Content helpers · Layout and shortcode helpers for lesson and content rendering.
src/lib/layouts.ts - Gamification · Points, streaks, and progression mechanics used by learner-facing features.
src/lib/gamification.ts - AI balancer · Client-side AI request selection and balancing logic.
src/lib/ai-balancer.ts - Public UI · Hero, features, and navigation for the marketing experience.
src/components/Hero.tsx
Connections 19
- 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.