# burakorkmez/codeflex-ai architecture

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

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

## Overview

This project is a full-stack web application – the “AI Fitness Assistant” – built with Next.js, React, Tailwind CSS, and Shadcn UI. It integrates several key external services, including Clerk for authentication, Convex as a real-time database, Vapi for the voice AI assistant, and Gemini AI for generating personalized fitness programs.

##### Main Components

a. Frontend (Next.js + React)
- Pages and routes are found under the src/app directory. These include authentication flows (sign-in/sign-up), profile pages, and a “generate-program” page.
- Components are organized in the src/components folder, which includes shared UI components such as Navbar, Footer, and other reusable UI elements (some of which are built using Shadcn UI).

b. Backend & API Integration (Next.js Server-side)
- Although the app uses Next.js’s hybrid server/client capabilities, there is a middleware.ts file, possibly for request handling, routing, or authentication checks.
- There are hints of server-side logic and API routes, even if they are not segregated in an explicit “api” directory. The application leverages server components and dynamic imports.

c. Database (Convex)
- The convex directory contains configurations and generated files (e.g., api.js, server.js, dataModel) that manage interactions with Convex, which acts as a real-time database.
- That files like auth.config.ts, http.ts, and plans.ts in the convex folder indicate custom database operations and business logic related to user plans and authentication.

d. Authentication & User Management (Clerk)
- Authentication is managed using Clerk, as found in environment variables and the ConvexClerkProvider in the src/providers directory.
- The integration is highlighted in the README and is crucial for both the sign-in/sign-up flows and user session management.

e. External Services Integration
- Vapi (Voice AI) is integrated to handle the conversational aspects of the assistant.
- Gemini AI provides the LLM functionality used for generating personalized workout and diet plans.
- These services are referenced in the README and managed through environment variables.

##### Relationships and Interactions

- The Next.js frontend communicates with backend components (server functions/middleware) that, in turn, interact with the Convex real-time database.
- Authentication flows on the UI leverage Clerk for secure user management, and a provider (ConvexClerkProvider) connects the authentication status to database operations.
- The voice command functionality uses Vapi integration to relay user inputs (and possibly trigger workflows) and interacts with the Gemini AI service to generate tailored fitness programs.
- UI components like forms and interactive elements trigger API calls that exchange data between the frontend and the database (Convex), managed by the corresponding routes and middleware.

##### Architectural Patterns and Design Principles

- Separation of Concerns: The application clearly separates presentation (frontend UI in src/app and src/components) from data management (Convex in the convex folder) and authentication/governance (Clerk).
- Client/Server Components: Use of Next.js allows for a mix of client and server components, optimizing both static and dynamic content rendering.
- Modular Design: By structuring the code into directories such as src/components, src/lib, and src/providers, the project promotes modularity and reuse.
- Real-Time Data Handling: Using Convex as a real-time database suggests design patterns oriented around live updates and immediate data synchronization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F1["Next.js/React UI - Pages & Routes"]:::frontend
        F2["Next.js/React UI - Shared Components"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B1["Next.js Server-side Logic"]:::backend
        M1["Middleware (src/middleware.ts)"]:::backend
    end

    %% Authentication
    subgraph "Authentication"
        A1["Clerk Authentication Provider"]:::auth
    end

    %% Database Layer
    subgraph "Database Layer"
        D1["Convex - Real-Time Database"]:::database
        subgraph "Convex Files"
            CF1["api.js"]:::database
            CF2["auth.config.ts"]:::database
            CF3["http.ts"]:::database
            CF4["plans.ts"]:::database
            CF5["schema.ts"]:::database
            CF6["users.ts"]:::database
        end
    end

    %% External Services
    subgraph "External Services"
        E1["Vapi (Voice AI)"]:::external
        E2["Gemini AI (Fitness Programs)"]:::external
    end

    %% Connections
    F1 -->|"sign-in_flow"| A1
    F1 -->|"API_requests"| M1
    M1 -->|"db_operations"| D1
    A1 -->|"provider_link"| D1
    M1 -->|"voice_integration"| E1
    M1 -->|"llm_processing"| E2

    %% Convex Database contains its files
    D1 --> CF1
    D1 --> CF2
    D1 --> CF3
    D1 --> CF4
    D1 --> CF5
    D1 --> CF6

    %% Click Events
    click F1 "https://github.com/burakorkmez/codeflex-ai/tree/master/src/app"
    click F2 "https://github.com/burakorkmez/codeflex-ai/tree/master/src/components"
    click M1 "https://github.com/burakorkmez/codeflex-ai/blob/master/src/middleware.ts"
    click A1 "https://github.com/burakorkmez/codeflex-ai/blob/master/src/providers/ConvexClerkProvider.tsx"
    click E1 "https://github.com/burakorkmez/codeflex-ai/blob/master/src/lib/vapi.ts"
    click CF1 "https://github.com/burakorkmez/codeflex-ai/blob/master/convex/_generated/api.js"
    click CF2 "https://github.com/burakorkmez/codeflex-ai/blob/master/convex/auth.config.ts"
    click CF3 "https://github.com/burakorkmez/codeflex-ai/blob/master/convex/http.ts"
    click CF4 "https://github.com/burakorkmez/codeflex-ai/blob/master/convex/plans.ts"
    click CF5 "https://github.com/burakorkmez/codeflex-ai/blob/master/convex/schema.ts"
    click CF6 "https://github.com/burakorkmez/codeflex-ai/blob/master/convex/users.ts"

    %% Styles
    classDef frontend fill:#ffeeee,stroke:#cc0000,stroke-width:2px;
    classDef backend fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef auth fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef database fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
```
