How zakamm/intellex works
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: input-form.tsx Survey flow · use-auth.ts Auth hook · get-user-data.ts User data · page.tsx Dashboard
Components 26
App routes
Next.js App Router pages and server route handlers.
- Home · Public entry point and starting route.
app/page.tsx - Shell · Global app shell, metadata, and providers.
app/layout.tsx - Dashboard · Authenticated overview of user status and progress.
app/dashboard/page.tsx - Create · Dashboard sub-route for creating or configuring user goals.
app/dashboard/create/page.tsx - Survey · Multi-step intake flow for skills and interests.
app/form/page.tsx - Session · Real-time peer learning and video session surface.
app/session/page.tsx - Leaderboard · Public view of learner standings and rewards.
app/leaderboard/page.tsx - Verbwire API · Server-side bridge for NFT or reward issuance.
app/api/verbwire/route.ts
UI components
Shared layout, feature widgets, and design-system primitives.
- Navbar · Top-level navigation shared across pages.
components/component/navbar.tsx - Profile icon · User account display and quick profile access.
components/component/profile-icon.tsx - Theme toggle · Cross-cutting light/dark mode control.
components/component/mode-toggle.tsx - Summary · Compact profile or progress summary for the dashboard.
components/component/summary/summary.tsx - Survey flow · Survey UI for collecting user input across steps.
components/component/survey/input-form.tsx - Questions · Question rendering and progression for onboarding.
components/component/survey/survey-questions.tsx - Survey done · Completion state shown after the intake flow.
components/component/survey/survey-complete.tsx - Thanks view · Final acknowledgment after submitting survey responses.
components/component/survey/thanks-survey.tsx - UI kit · Reusable form, card, table, button, and navigation primitives.
components/ui/button.tsx - Theme provider · Application-wide theme context wiring.
components/theme-provider.tsx
Application logic
Auth, user-state, question data, and shared helpers.
- Auth hook · Client auth state and user session boundary.
lib/hooks/use-auth.ts - Sign-in flow · Creates or signs in a user against the identity backend.
lib/sign-in-or-create.ts - User data · Loads application-specific profile and match state.
lib/get-user-data.ts - Firebase · Central persistence and authentication integration.
lib/firebase.ts - Questions data · Question set used by the onboarding survey.
lib/questions.ts - Utils · General-purpose shared utility functions.
lib/utils.ts
External services
Managed services and integrations used by the app.
- 100ms · External live-session provider for video and peer interaction.
- Verbwire · External NFT or reward minting service.
Connections 30
- 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.