# jaiteshg/codeflex architecture

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

- Interactive diagram: https://gitdiagram.com/jaiteshg/codeflex
- Repository: https://github.com/jaiteshg/codeflex

## Overview

1. This repo is a Next.js App Router application with three major boundaries: the UI layer in `src/app` and `src/components`, the realtime backend in `convex`, and external auth/AI services (Clerk, Vapi, Gemini) wired in through environment variables and small integration modules.

2. The presentation layer is split between public/marketing pages and authenticated app pages. The root route (`src/app/page.tsx`) is the entry point, while `src/app/(auth)/sign-in` and `src/app/(auth)/sign-up` host Clerk’s auth UI, `src/app/generate-program/page.tsx` drives the assistant-based program creation flow, and `src/app/profile/page.tsx` shows a user’s saved fitness plans.

3. Shared UI chrome lives in reusable components such as `Navbar`, `Footer`, `CornerElements`, `TerminalOverlay`, `ProfileHeader`, `UserPrograms`, and `NoFitnessPlan`. This suggests the app is designed around a branded shell plus a few feature-specific panels rather than a large page hierarchy.

4. Authentication is a first-class subsystem. Clerk handles sign-in/sign-up and user identity, while `src/middleware.ts` likely protects authenticated routes and redirects unauthenticated users. The `ConvexClerkProvider` in `src/providers` bridges Clerk session state into Convex so backend queries/mutations know who the user is.

5. The fitness-plan generation flow is voice-driven. `src/lib/vapi.ts` encapsulates the Vapi client integration, and the `generate-program` screen likely uses `TerminalOverlay` plus Vapi’s workflow id/API key to start a conversational AI session that collects fitness goals, injuries, preferences, and dietary constraints.

6. Vapi is acting as the conversation orchestration layer, while Gemini is the LLM used behind that workflow to produce the actual personalized workout and diet output. From an architecture standpoint, the app itself does not appear to call the model directly; it initiates a workflow and receives results back through the assistant pipeline.

7. Convex is the application database and realtime state layer. `convex/schema.ts` defines the collections, `convex/users.ts` and `convex/plans.ts` hold domain operations, and the generated client in `convex/_generated` is consumed from the Next.js app for typed reads/writes. This is the primary persistence boundary for users and fitness programs.

8. The data model appears centered on users and plans, with the business rule that a user can have multiple programs but only the latest one is active. That behavior is reflected in the README and the presence of dedicated `plans` and `users` modules, plus the profile UI that likely lists historical programs.

9. `convex/http.ts` indicates there is at least one HTTP-facing backend surface in addition to direct Convex queries/mutations. In this kind of architecture, that file usually serves webhook-style traffic or external callbacks from services like Vapi, keeping third-party integration logic out of the React app.

10. Styling and UI primitives are handled with Tailwind and shadcn/ui. The `src/components/ui` folder contains low-level building blocks like button, card, accordion, and tabs, while `src/app/globals.css` and `public/globals.css` provide the global theme layer.

11. The overall runtime flow is: user lands on the Next.js frontend, authenticates through Clerk, uses the voice assistant to describe a desired fitness profile, Vapi/Gemini generates the plan, Convex persists the user and plan records, and the profile page reads back the stored plans in realtime.

12. In diagram terms, the important external services are Clerk for identity, Vapi for conversational AI orchestration, Gemini for generation, Convex for persistence/realtime sync, and Next.js/Vercel as the application host. The architecture is mostly frontend-driven, with Convex providing the backend domain boundary rather than a separate custom API server.

Main entry points: [`convex/_generated/api.js`](https://github.com/jaiteshg/codeflex/blob/main/convex/_generated/api.js) (Generated Client), [`src/app/layout.tsx`](https://github.com/jaiteshg/codeflex/blob/main/src/app/layout.tsx) (App Shell), [`src/app/profile/page.tsx`](https://github.com/jaiteshg/codeflex/blob/main/src/app/profile/page.tsx) (Profile), [`src/app/generate-program/page.tsx`](https://github.com/jaiteshg/codeflex/blob/main/src/app/generate-program/page.tsx) (Generate Plan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Frontend"]
  node_app_root["Home<br/>marketing page<br/>[page.tsx]"]
  node_app_layout["App Shell<br/>layout<br/>[layout.tsx]"]
  node_auth_signin["Sign In<br/>auth route<br/>[page.tsx]"]
  node_auth_signup["Sign Up<br/>auth route<br/>[page.tsx]"]
  node_generate_page["Generate Plan<br/>assistant flow<br/>[page.tsx]"]
  node_profile_page["Profile<br/>account page<br/>[page.tsx]"]
  node_navbar["Navbar<br/>navigation chrome<br/>[Navbar.tsx]"]
  node_footer["Footer<br/>page chrome<br/>[Footer.tsx]"]
  node_terminal_overlay["Terminal UI<br/>assistant ui"]
  node_profile_header["Profile Header<br/>profile chrome<br/>[ProfileHeader.tsx]"]
  node_user_programs["User Programs<br/>plan list<br/>[UserPrograms.tsx]"]
  node_no_plan["No Plan<br/>empty state<br/>[NoFitnessPlan.tsx]"]
  node_corner_elements["Corner Elements<br/>decorative chrome<br/>[CornerElements.tsx]"]
  node_convex_provider["Clerk Bridge<br/>provider"]
  node_middleware["Middleware<br/>route guard<br/>[middleware.ts]"]
end

subgraph group_backend["Convex Backend"]
  node_convex_schema["Schema<br/>data model<br/>[schema.ts]"]
  node_convex_users["Users<br/>domain ops<br/>[users.ts]"]
  node_convex_plans["Plans<br/>domain ops<br/>[plans.ts]"]
  node_convex_http["HTTP Surface<br/>webhook api<br/>[http.ts]"]
  node_convex_gen["Generated Client<br/>typed client<br/>[api.js]"]
end

subgraph group_integrations["External Services"]
  node_vapi_client["Vapi Client<br/>assistant integration<br/>[vapi.ts]"]
  node_clerk(("Clerk<br/>identity service"))
  node_gemini(("Gemini<br/>llm service"))
end

subgraph group_ui["UI Primitives"]
end

node_app_layout -->|"renders"| node_navbar
node_app_layout -->|"renders"| node_footer
node_app_layout -->|"renders"| node_corner_elements
node_app_layout -->|"wraps"| node_convex_provider
node_app_root -->|"uses"| node_navbar
node_app_root -->|"uses"| node_footer
node_generate_page -->|"uses"| node_terminal_overlay
node_profile_page -->|"uses"| node_profile_header
node_profile_page -->|"uses"| node_user_programs
node_profile_page -->|"fallback"| node_no_plan
node_middleware -.->|"redirects"| node_auth_signin
node_middleware -.->|"redirects"| node_auth_signup
node_convex_provider -->|"bridges"| node_clerk
node_auth_signin -->|"delegates"| node_clerk
node_auth_signup -->|"delegates"| node_clerk
node_generate_page -->|"starts"| node_vapi_client
node_vapi_client -.->|"orchestrates"| node_gemini
node_vapi_client -.->|"callbacks"| node_convex_http
node_convex_http -->|"writes"| node_convex_plans
node_convex_users -->|"implements"| node_convex_schema
node_convex_plans -->|"implements"| node_convex_schema
node_convex_gen -->|"types"| node_convex_users
node_convex_gen -->|"types"| node_convex_plans
node_profile_page -->|"reads"| node_convex_gen
node_generate_page -->|"writes"| node_convex_gen
node_convex_provider -->|"enables"| node_convex_gen

click node_app_root "https://github.com/jaiteshg/codeflex/blob/main/src/app/page.tsx"
click node_app_layout "https://github.com/jaiteshg/codeflex/blob/main/src/app/layout.tsx"
click node_auth_signin "https://github.com/jaiteshg/codeflex/blob/main/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
click node_auth_signup "https://github.com/jaiteshg/codeflex/blob/main/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx"
click node_generate_page "https://github.com/jaiteshg/codeflex/blob/main/src/app/generate-program/page.tsx"
click node_profile_page "https://github.com/jaiteshg/codeflex/blob/main/src/app/profile/page.tsx"
click node_navbar "https://github.com/jaiteshg/codeflex/blob/main/src/components/Navbar.tsx"
click node_footer "https://github.com/jaiteshg/codeflex/blob/main/src/components/Footer.tsx"
click node_terminal_overlay "https://github.com/jaiteshg/codeflex/blob/main/src/components/TerminalOverlay.tsx"
click node_profile_header "https://github.com/jaiteshg/codeflex/blob/main/src/components/ProfileHeader.tsx"
click node_user_programs "https://github.com/jaiteshg/codeflex/blob/main/src/components/UserPrograms.tsx"
click node_no_plan "https://github.com/jaiteshg/codeflex/blob/main/src/components/NoFitnessPlan.tsx"
click node_corner_elements "https://github.com/jaiteshg/codeflex/blob/main/src/components/CornerElements.tsx"
click node_convex_provider "https://github.com/jaiteshg/codeflex/blob/main/src/providers/ConvexClerkProvider.tsx"
click node_middleware "https://github.com/jaiteshg/codeflex/blob/main/src/middleware.ts"
click node_vapi_client "https://github.com/jaiteshg/codeflex/blob/main/src/lib/vapi.ts"
click node_convex_schema "https://github.com/jaiteshg/codeflex/blob/main/convex/schema.ts"
click node_convex_users "https://github.com/jaiteshg/codeflex/blob/main/convex/users.ts"
click node_convex_plans "https://github.com/jaiteshg/codeflex/blob/main/convex/plans.ts"
click node_convex_http "https://github.com/jaiteshg/codeflex/blob/main/convex/http.ts"
click node_convex_gen "https://github.com/jaiteshg/codeflex/blob/main/convex/_generated/api.js"

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_app_root,node_app_layout,node_auth_signin,node_auth_signup,node_generate_page,node_profile_page,node_navbar,node_footer,node_terminal_overlay,node_profile_header,node_user_programs,node_no_plan,node_corner_elements,node_convex_provider,node_middleware toneBlue
class node_convex_schema,node_convex_users,node_convex_plans,node_convex_http,node_convex_gen toneAmber
class node_vapi_client,node_clerk,node_gemini toneMint
```

## Components

### Next.js Frontend

App Router pages, shared chrome, and client-side flow entrypoints.

- [Home](https://github.com/jaiteshg/codeflex/blob/main/src/app/page.tsx): marketing page · Public landing page and primary entry into the app. · `src/app/page.tsx`
- [App Shell](https://github.com/jaiteshg/codeflex/blob/main/src/app/layout.tsx): layout · Top-level application layout and shared providers. · `src/app/layout.tsx`
- [Sign In](https://github.com/jaiteshg/codeflex/blob/main/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx): auth route · Clerk sign-in route mounted under the App Router. · `src/app/(auth)/sign-in/[[...sign-in]]/page.tsx`
- [Sign Up](https://github.com/jaiteshg/codeflex/blob/main/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx): auth route · Clerk sign-up route mounted under the App Router. · `src/app/(auth)/sign-up/[[...sign-up]]/page.tsx`
- [Generate Plan](https://github.com/jaiteshg/codeflex/blob/main/src/app/generate-program/page.tsx): assistant flow · Voice-driven fitness program creation screen. · `src/app/generate-program/page.tsx`
- [Profile](https://github.com/jaiteshg/codeflex/blob/main/src/app/profile/page.tsx): account page · Shows the user's saved fitness plans and latest program. · `src/app/profile/page.tsx`
- [Navbar](https://github.com/jaiteshg/codeflex/blob/main/src/components/Navbar.tsx): navigation chrome · Shared top-level navigation component. · `src/components/Navbar.tsx`
- [Footer](https://github.com/jaiteshg/codeflex/blob/main/src/components/Footer.tsx): page chrome · Shared footer used across the public-facing shell. · `src/components/Footer.tsx`
- [Terminal UI](https://github.com/jaiteshg/codeflex/blob/main/src/components/TerminalOverlay.tsx): assistant ui · Branded overlay used during the voice/program generation experience. · `src/components/TerminalOverlay.tsx`
- [Profile Header](https://github.com/jaiteshg/codeflex/blob/main/src/components/ProfileHeader.tsx): profile chrome · Header block for the profile and plan history view. · `src/components/ProfileHeader.tsx`
- [User Programs](https://github.com/jaiteshg/codeflex/blob/main/src/components/UserPrograms.tsx): plan list · Renders a user's saved fitness plans. · `src/components/UserPrograms.tsx`
- [No Plan](https://github.com/jaiteshg/codeflex/blob/main/src/components/NoFitnessPlan.tsx): empty state · Fallback view when the user has no saved fitness plan. · `src/components/NoFitnessPlan.tsx`
- [Corner Elements](https://github.com/jaiteshg/codeflex/blob/main/src/components/CornerElements.tsx): decorative chrome · Decorative layout accents for branded presentation. · `src/components/CornerElements.tsx`
- [Clerk Bridge](https://github.com/jaiteshg/codeflex/blob/main/src/providers/ConvexClerkProvider.tsx): provider · Connects Clerk session state into Convex for authenticated data access. · `src/providers/ConvexClerkProvider.tsx`
- [Middleware](https://github.com/jaiteshg/codeflex/blob/main/src/middleware.ts): route guard · Protects authenticated routes and handles redirects. · `src/middleware.ts`

### Convex Backend

Realtime persistence, domain logic, and external callback surface.

- [Schema](https://github.com/jaiteshg/codeflex/blob/main/convex/schema.ts): data model · Defines users and plans collections. · `convex/schema.ts`
- [Users](https://github.com/jaiteshg/codeflex/blob/main/convex/users.ts): domain ops · User-related Convex queries and mutations. · `convex/users.ts`
- [Plans](https://github.com/jaiteshg/codeflex/blob/main/convex/plans.ts): domain ops · Fitness plan persistence and retrieval logic. · `convex/plans.ts`
- [HTTP Surface](https://github.com/jaiteshg/codeflex/blob/main/convex/http.ts): webhook api · External callback or webhook entrypoint for integrations. · `convex/http.ts`
- [Generated Client](https://github.com/jaiteshg/codeflex/blob/main/convex/_generated/api.js): typed client · Generated Convex API bindings consumed by the app. · `convex/_generated/api.js`

### External Services

Identity and AI services used by the application.

- [Vapi Client](https://github.com/jaiteshg/codeflex/blob/main/src/lib/vapi.ts): assistant integration · Encapsulates the conversational AI workflow client. · `src/lib/vapi.ts`
- **Clerk**: identity service · Authentication and user identity provider.
- **Gemini**: llm service · Model used to generate personalized workout and diet plans.

## Connections

- App Shell → Navbar: renders · Shared shell composes navigation.
- App Shell → Footer: renders · Shared shell composes footer.
- App Shell → Corner Elements: renders · Shared branded presentation layer.
- App Shell → Clerk Bridge: wraps · Provides authenticated Convex access to the app.
- Home → Navbar: uses · Landing page uses shared navigation.
- Home → Footer: uses · Landing page uses shared footer.
- Generate Plan → Terminal UI: uses · Assistant flow is presented through the terminal-style overlay.
- Profile → Profile Header: uses · Profile view starts with a summary header.
- Profile → User Programs: uses · Profile view lists saved plans.
- Profile → No Plan: fallback · Empty state when no plans exist.
- Middleware → Sign In: redirects · Unauthenticated users are sent to sign-in.
- Middleware → Sign Up: redirects · Unauthenticated users can reach sign-up.
- Clerk Bridge → Clerk: bridges · Session identity is forwarded from Clerk into Convex.
- Sign In → Clerk: delegates · Sign-in UI is handled by Clerk.
- Sign Up → Clerk: delegates · Sign-up UI is handled by Clerk.
- Generate Plan → Vapi Client: starts · Program creation launches the voice assistant workflow.
- Vapi Client → Gemini: orchestrates · Vapi coordinates generation using Gemini behind the scenes.
- Vapi Client → HTTP Surface: callbacks · Workflow results can arrive through backend HTTP callbacks.
- HTTP Surface → Plans: writes · External events are persisted as fitness plans.
- Users → Schema: implements · User operations follow the shared schema.
- Plans → Schema: implements · Plan operations follow the shared schema.
- Generated Client → Users: types · Generated client exposes user operations.
- Generated Client → Plans: types · Generated client exposes plan operations.
- Profile → Generated Client: reads · Profile page loads user plans through typed Convex bindings.
- Generate Plan → Generated Client: writes · Generated plan data is persisted through Convex.
- Clerk Bridge → Generated Client: enables · Provider makes typed Convex access available in the UI.