# zakamm/intellex architecture

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

- Interactive diagram: https://gitdiagram.com/zakamm/intellex
- Repository: https://github.com/zakamm/intellex

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application, centered around a client-heavy React UI with a small serverless API layer.
   - The repo is organized around user-facing product flows: landing, onboarding/form capture, dashboard, live session, and leaderboard.

2. **Primary product flow**
   - Users enter through `app/page.tsx` and then move into the app’s main areas: `app/form`, `app/dashboard`, `app/session`, and `app/leaderboard`.
   - The app is clearly built around a **skill-matching and peer-learning loop**: capture user interests/skills, match them with others, run a live session, then surface progress on a leaderboard.

3. **Authentication and user state boundary**
   - `lib/hooks/use-auth.ts` and `lib/sign-in-or-create.ts` indicate a dedicated auth layer that likely bridges the UI to Firebase-backed user identity.
   - `lib/get-user-data.ts` suggests user profile and state are fetched separately from auth, which is important for the architecture diagram: **identity is one boundary, profile/matching data is another**.

4. **Backend and persistence**
   - `lib/firebase.ts` is the central Firebase integration point.
   - Firebase is the main persistence/auth backend for user records, likely storing profiles, match preferences, and leaderboard-related data.
   - The app appears to rely on Firebase as its primary application database rather than a custom API backend.

5. **Onboarding and skill capture**
   - The `app/form` route and `components/component/survey/*` are a dedicated intake subsystem.
   - `lib/questions.ts` provides the question set, while `input-form.tsx`, `survey-questions.tsx`, `survey-complete.tsx`, and `thanks-survey.tsx` form a multi-step survey flow.
   - This is the data-entry path that likely feeds the matching logic and user profile creation.

6. **Dashboard and user workspace**
   - `app/dashboard/page.tsx` and `app/dashboard/create/page.tsx` represent the core authenticated workspace.
   - The dashboard likely aggregates user status, matches, and next actions, while the create flow seems to support setting up a new profile or learning goal.
   - `components/component/summary/summary.tsx` suggests the dashboard includes a summarized view of the user’s skill profile or session progress.

7. **Live session subsystem**
   - `app/session/page.tsx` is the dedicated runtime surface for peer-to-peer learning sessions.
   - The README says the build is currently failing around the video-call feature using **100ms**, so the session boundary should be drawn as an integration with an external real-time communications service.
   - This subsystem is distinct from Firebase: Firebase manages app state, while the session page handles real-time interaction.

8. **Leaderboard and rewards**
   - `app/leaderboard/page.tsx` is the public ranking surface for weekly learners.
   - The README’s NFT reward feature maps to the serverless API route under `app/api/verbwire/route.ts`, which is the integration point to **Verbwire** for NFT minting or reward issuance.
   - This makes the rewards flow a separate service boundary: leaderboard calculation in-app, NFT action via external API.

9. **API layer**
   - The only explicit backend route is `app/api/verbwire/route.ts`.
   - That route is the bridge between the Next.js app and Verbwire, so it likely handles secure server-side API calls rather than exposing the key to the client.
   - Architecturally, this is the app’s main custom backend endpoint.

10. **UI/component structure**
   - `components/component/*` contains feature-specific reusable UI, such as navbar, profile icon, mode toggle, dots, survey components, and summary.
   - `components/ui/*` is a shared design-system layer, likely generated or adapted from shadcn/ui, used across pages for buttons, forms, tables, cards, and menus.
   - `components/theme-provider.tsx` and `components/component/mode-toggle.tsx` show that theming is a cross-cutting concern, not tied to any one page.

11. **Styling and app shell**
   - `app/layout.tsx`, `app/globals.css`, `tailwind.config.js`, and `postcss.config.js` define the global shell and styling system.
   - Tailwind CSS is the main styling mechanism, with theme support layered into the layout.

12. **What to draw as the main architectural boundaries**
   - **Client pages and components**: landing, onboarding, dashboard, session, leaderboard.
   - **Firebase backend**: auth, user data, and app state.
   - **Verbwire API integration**: NFT reward issuance.
   - **Real-time session provider**: 100ms-based video call layer referenced by the README.
   - **Shared UI library**: reusable design-system components and survey/dashboard widgets.

13. **End-to-end data flow**
   - A user authenticates, profile state is created or loaded through Firebase helpers, completes the survey/form, and then uses the dashboard to view matches or progress.
   - They join a live session through the session page, and their activity contributes to leaderboard standings.
   - Weekly winners can trigger the Verbwire-backed NFT reward path.

14. **Deployment/runtime context**
   - The stack is Next.js + React + TypeScript on Vercel, with Firebase and Verbwire as external managed services.
   - This is not a monolithic backend app; it is a frontend-first product with one small serverless integration route and several service dependencies.

Main entry points: [`components/component/survey/input-form.tsx`](https://github.com/zakamm/intellex/blob/master/components/component/survey/input-form.tsx) (Survey flow), [`lib/hooks/use-auth.ts`](https://github.com/zakamm/intellex/blob/master/lib/hooks/use-auth.ts) (Auth hook), [`lib/get-user-data.ts`](https://github.com/zakamm/intellex/blob/master/lib/get-user-data.ts) (User data), [`app/dashboard/page.tsx`](https://github.com/zakamm/intellex/blob/master/app/dashboard/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_home["Home<br/>landing page<br/>[page.tsx]"]
  node_layout["Shell<br/>app layout<br/>[layout.tsx]"]
  node_dashboard["Dashboard<br/>workspace page<br/>[page.tsx]"]
  node_dashboard_create["Create<br/>dashboard flow<br/>[page.tsx]"]
  node_form["Survey<br/>onboarding page<br/>[page.tsx]"]
  node_session["Session<br/>[page.tsx]"]
  node_leaderboard["Leaderboard<br/>ranking page<br/>[page.tsx]"]
  node_verbwire_api["Verbwire API<br/>serverless route<br/>[route.ts]"]
end

subgraph group_components["UI components"]
  node_navbar["Navbar<br/>navigation component<br/>[navbar.tsx]"]
  node_profile_icon(("Profile icon<br/>account widget<br/>[profile-icon.tsx]"))
  node_mode_toggle(("Theme toggle<br/>theme control<br/>[mode-toggle.tsx]"))
  node_summary["Summary<br/>dashboard widget<br/>[summary.tsx]"]
  node_survey_flow["Survey flow<br/>onboarding widgets<br/>[input-form.tsx]"]
  node_survey_questions["Questions<br/>survey step"]
  node_survey_done["Survey done<br/>completion view"]
  node_thanks_survey["Thanks view<br/>post-submit view<br/>[thanks-survey.tsx]"]
  node_ui_kit["UI kit<br/>design system<br/>[button.tsx]"]
  node_theme_provider(("Theme provider<br/>[theme-provider.tsx]"))
end

subgraph group_lib["Application logic"]
  node_auth(("Auth hook<br/>identity helper<br/>[use-auth.ts]"))
  node_signin(("Sign-in flow<br/>auth helper"))
  node_user_data(("User data<br/>profile helper<br/>[get-user-data.ts]"))
  node_firebase[("Firebase<br/>backend integration<br/>[firebase.ts]")]
  node_questions["Questions data<br/>content config<br/>[questions.ts]"]
  node_utils(("Utils<br/>shared helper<br/>[utils.ts]"))
end

subgraph group_external["External services"]
  node_realtime[("100ms<br/>realtime service")]
  node_verbwire[("Verbwire<br/>reward service")]
end

node_home -->|"uses"| node_navbar
node_home -->|"entry"| node_auth
node_layout -->|"wraps"| node_theme_provider
node_layout -->|"includes"| node_navbar
node_navbar -->|"shows"| node_profile_icon
node_navbar -->|"shows"| node_mode_toggle
node_dashboard -->|"gates"| node_auth
node_dashboard -->|"loads"| node_user_data
node_dashboard -->|"renders"| node_summary
node_dashboard -->|"navigates"| node_dashboard_create
node_dashboard_create -->|"updates"| node_user_data
node_form -->|"composes"| node_survey_flow
node_survey_flow -->|"steps"| node_survey_questions
node_survey_flow -->|"completes"| node_survey_done
node_survey_flow -->|"finishes"| node_thanks_survey
node_survey_questions -->|"uses"| node_questions
node_survey_flow -->|"captures"| node_user_data
node_user_data -->|"reads"| node_firebase
node_auth -->|"authenticates"| node_firebase
node_signin -->|"uses"| node_firebase
node_session -->|"connects"| node_realtime
node_session -->|"gates"| node_auth
node_leaderboard -->|"reads"| node_user_data
node_leaderboard -->|"triggers"| node_verbwire_api
node_verbwire_api -->|"calls"| node_verbwire
node_summary -->|"builds on"| node_ui_kit
node_survey_flow -->|"builds on"| node_ui_kit
node_mode_toggle -->|"controls"| node_theme_provider
node_profile_icon -->|"reflects"| node_auth
node_utils -->|"supports"| node_ui_kit

click node_home "https://github.com/zakamm/intellex/blob/master/app/page.tsx"
click node_layout "https://github.com/zakamm/intellex/blob/master/app/layout.tsx"
click node_dashboard "https://github.com/zakamm/intellex/blob/master/app/dashboard/page.tsx"
click node_dashboard_create "https://github.com/zakamm/intellex/blob/master/app/dashboard/create/page.tsx"
click node_form "https://github.com/zakamm/intellex/blob/master/app/form/page.tsx"
click node_session "https://github.com/zakamm/intellex/blob/master/app/session/page.tsx"
click node_leaderboard "https://github.com/zakamm/intellex/blob/master/app/leaderboard/page.tsx"
click node_verbwire_api "https://github.com/zakamm/intellex/blob/master/app/api/verbwire/route.ts"
click node_navbar "https://github.com/zakamm/intellex/blob/master/components/component/navbar.tsx"
click node_profile_icon "https://github.com/zakamm/intellex/blob/master/components/component/profile-icon.tsx"
click node_mode_toggle "https://github.com/zakamm/intellex/blob/master/components/component/mode-toggle.tsx"
click node_summary "https://github.com/zakamm/intellex/blob/master/components/component/summary/summary.tsx"
click node_survey_flow "https://github.com/zakamm/intellex/blob/master/components/component/survey/input-form.tsx"
click node_survey_questions "https://github.com/zakamm/intellex/blob/master/components/component/survey/survey-questions.tsx"
click node_survey_done "https://github.com/zakamm/intellex/blob/master/components/component/survey/survey-complete.tsx"
click node_thanks_survey "https://github.com/zakamm/intellex/blob/master/components/component/survey/thanks-survey.tsx"
click node_ui_kit "https://github.com/zakamm/intellex/blob/master/components/ui/button.tsx"
click node_theme_provider "https://github.com/zakamm/intellex/blob/master/components/theme-provider.tsx"
click node_auth "https://github.com/zakamm/intellex/blob/master/lib/hooks/use-auth.ts"
click node_signin "https://github.com/zakamm/intellex/blob/master/lib/sign-in-or-create.ts"
click node_user_data "https://github.com/zakamm/intellex/blob/master/lib/get-user-data.ts"
click node_firebase "https://github.com/zakamm/intellex/blob/master/lib/firebase.ts"
click node_questions "https://github.com/zakamm/intellex/blob/master/lib/questions.ts"
click node_utils "https://github.com/zakamm/intellex/blob/master/lib/utils.ts"

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_home,node_layout,node_dashboard,node_dashboard_create,node_form,node_session,node_leaderboard,node_verbwire_api toneBlue
class node_navbar,node_profile_icon,node_mode_toggle,node_summary,node_survey_flow,node_survey_questions,node_survey_done,node_thanks_survey,node_ui_kit,node_theme_provider toneAmber
class node_auth,node_signin,node_user_data,node_firebase,node_questions,node_utils toneMint
class node_realtime,node_verbwire toneRose
```

## Components

### App routes

Next.js App Router pages and server route handlers.

- [Home](https://github.com/zakamm/intellex/blob/master/app/page.tsx): landing page · Public entry point and starting route. · `app/page.tsx`
- [Shell](https://github.com/zakamm/intellex/blob/master/app/layout.tsx): app layout · Global app shell, metadata, and providers. · `app/layout.tsx`
- [Dashboard](https://github.com/zakamm/intellex/blob/master/app/dashboard/page.tsx): workspace page · Authenticated overview of user status and progress. · `app/dashboard/page.tsx`
- [Create](https://github.com/zakamm/intellex/blob/master/app/dashboard/create/page.tsx): dashboard flow · Dashboard sub-route for creating or configuring user goals. · `app/dashboard/create/page.tsx`
- [Survey](https://github.com/zakamm/intellex/blob/master/app/form/page.tsx): onboarding page · Multi-step intake flow for skills and interests. · `app/form/page.tsx`
- [Session](https://github.com/zakamm/intellex/blob/master/app/session/page.tsx): live session page · Real-time peer learning and video session surface. · `app/session/page.tsx`
- [Leaderboard](https://github.com/zakamm/intellex/blob/master/app/leaderboard/page.tsx): ranking page · Public view of learner standings and rewards. · `app/leaderboard/page.tsx`
- [Verbwire API](https://github.com/zakamm/intellex/blob/master/app/api/verbwire/route.ts): serverless route · Server-side bridge for NFT or reward issuance. · `app/api/verbwire/route.ts`

### UI components

Shared layout, feature widgets, and design-system primitives.

- [Navbar](https://github.com/zakamm/intellex/blob/master/components/component/navbar.tsx): navigation component · Top-level navigation shared across pages. · `components/component/navbar.tsx`
- [Profile icon](https://github.com/zakamm/intellex/blob/master/components/component/profile-icon.tsx): account widget · User account display and quick profile access. · `components/component/profile-icon.tsx`
- [Theme toggle](https://github.com/zakamm/intellex/blob/master/components/component/mode-toggle.tsx): theme control · Cross-cutting light/dark mode control. · `components/component/mode-toggle.tsx`
- [Summary](https://github.com/zakamm/intellex/blob/master/components/component/summary/summary.tsx): dashboard widget · Compact profile or progress summary for the dashboard. · `components/component/summary/summary.tsx`
- [Survey flow](https://github.com/zakamm/intellex/blob/master/components/component/survey/input-form.tsx): onboarding widgets · Survey UI for collecting user input across steps. · `components/component/survey/input-form.tsx`
- [Questions](https://github.com/zakamm/intellex/blob/master/components/component/survey/survey-questions.tsx): survey step · Question rendering and progression for onboarding. · `components/component/survey/survey-questions.tsx`
- [Survey done](https://github.com/zakamm/intellex/blob/master/components/component/survey/survey-complete.tsx): completion view · Completion state shown after the intake flow. · `components/component/survey/survey-complete.tsx`
- [Thanks view](https://github.com/zakamm/intellex/blob/master/components/component/survey/thanks-survey.tsx): post-submit view · Final acknowledgment after submitting survey responses. · `components/component/survey/thanks-survey.tsx`
- [UI kit](https://github.com/zakamm/intellex/blob/master/components/ui/button.tsx): design system · Reusable form, card, table, button, and navigation primitives. · `components/ui/button.tsx`
- [Theme provider](https://github.com/zakamm/intellex/blob/master/components/theme-provider.tsx): provider · Application-wide theme context wiring. · `components/theme-provider.tsx`

### Application logic

Auth, user-state, question data, and shared helpers.

- [Auth hook](https://github.com/zakamm/intellex/blob/master/lib/hooks/use-auth.ts): identity helper · Client auth state and user session boundary. · `lib/hooks/use-auth.ts`
- [Sign-in flow](https://github.com/zakamm/intellex/blob/master/lib/sign-in-or-create.ts): auth helper · Creates or signs in a user against the identity backend. · `lib/sign-in-or-create.ts`
- [User data](https://github.com/zakamm/intellex/blob/master/lib/get-user-data.ts): profile helper · Loads application-specific profile and match state. · `lib/get-user-data.ts`
- [Firebase](https://github.com/zakamm/intellex/blob/master/lib/firebase.ts): backend integration · Central persistence and authentication integration. · `lib/firebase.ts`
- [Questions data](https://github.com/zakamm/intellex/blob/master/lib/questions.ts): content config · Question set used by the onboarding survey. · `lib/questions.ts`
- [Utils](https://github.com/zakamm/intellex/blob/master/lib/utils.ts): shared helper · General-purpose shared utility functions. · `lib/utils.ts`

### External services

Managed services and integrations used by the app.

- **100ms**: realtime service · External live-session provider for video and peer interaction.
- **Verbwire**: reward service · External NFT or reward minting service.

## Connections

- Home → Navbar: uses · Landing page renders shared navigation.
- Home → Auth hook: entry · Landing route can branch into authenticated state.
- Shell → Theme provider: wraps · Global layout installs theme context.
- Shell → Navbar: includes · Shared shell includes primary navigation.
- Navbar → Profile icon: shows · Navigation exposes account/profile access.
- Navbar → Theme toggle: shows · Navigation exposes theme switching.
- Dashboard → Auth hook: gates · Dashboard depends on authenticated user state.
- Dashboard → User data: loads · Dashboard renders profile and progress data.
- Dashboard → Summary: renders · Dashboard uses summary widget for status.
- Dashboard → Create: navigates · Dashboard links into create/configure flow.
- Create → User data: updates · Create flow likely writes or refreshes user profile state.
- Survey → Survey flow: composes · Survey route hosts the intake UI.
- Survey flow → Questions: steps · Survey flow advances through question screens.
- Survey flow → Survey done: completes · Survey flow ends in completion state.
- Survey flow → Thanks view: finishes · Submission flow ends with thank-you screen.
- Questions → Questions data: uses · Survey renders the configured question set.
- Survey flow → User data: captures · Survey inputs populate user profile/matching data.
- User data → Firebase: reads · User profile data is fetched from Firebase.
- Auth hook → Firebase: authenticates · Auth hook bridges to Firebase identity.
- Sign-in flow → Firebase: uses · Sign-in helper performs Firebase-backed identity operations.
- Session → 100ms: connects · Session page integrates the live-call provider.
- Session → Auth hook: gates · Live session access depends on signed-in user state.
- Leaderboard → User data: reads · Leaderboard derives standings from app user state.
- Leaderboard → Verbwire API: triggers · Leaderboard can invoke reward issuance flow.
- Verbwire API → Verbwire: calls · Server route forwards secure requests to Verbwire.
- Summary → UI kit: builds on · Dashboard summary is built from shared UI primitives.
- Survey flow → UI kit: builds on · Survey widgets rely on shared UI primitives.
- Theme toggle → Theme provider: controls · Theme toggle operates through theme context.
- Profile icon → Auth hook: reflects · Profile icon reflects signed-in user state.
- Utils → UI kit: supports · General helpers support shared UI behavior.
