# uday-4083/evolvai architecture

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

- Interactive diagram: https://gitdiagram.com/uday-4083/evolvai
- Repository: https://github.com/uday-4083/evolvai

## Overview

##### Main Components
- Client (Browser / Mobile)
- Frontend Next.js App Router (app/ directory pages & layouts)
- UI Component Library (Shadcn UI + Tailwind CSS in components/ui/)
- Authentication Service (Clerk)
- API Layer
– Next.js API Routes (app/api/inngest/route.js, other /api endpoints)
– Server Actions (actions/*.js)
- Business Logic & Utilities (app/lib/, lib/, hooks/)
- Background Job Processor (Inngest functions in lib/inngest/, triggered via API)
- Database (Neon DB Postgres via Prisma in prisma/schema.prisma + prisma client)
- AI Service (Google Gemini API)
- CDN / Static Assets (public/, globals.css)
- Hosting / Orchestration (Vercel serverless functions, Inngest dev/prod endpoints)

##### Relationships & Data Flows
a. User → Frontend pages (SSR/Server Components) → Server Actions or API calls
b. Frontend ↔ Clerk SDK (for sign‑in, sign‑up, session tokens)
c. API Routes & Server Actions → Business Logic in lib/helper.js, lib/utils.js → Prisma Client → Neon DB
d. API Routes → Inngest (enqueue background jobs like AI‑driven resume/cover‑letter generation)
e. Inngest Worker Functions → Prisma → Neon DB and/or Gemini API calls → update DB → trigger notifications or status updates
f. Frontend polls or subscribes to job status via Next.js API or using Inngest webhook callbacks
g. Frontend → Gemini API (via backend proxy in Server Actions or API Routes) for AI content generation

##### Architectural Patterns & Principles
– Full‑Stack Monorepo: React + Next.js (app router) tightly coupled with API and server‑side code.
– Server Components & Client Components: /app layouts and pages handle data fetching server‑side, UI components are client‑side.
– API Routes for both synchronous (CRUD) and asynchronous (Inngest jobs) operations.
– Background Job Pattern: decouple heavy AI tasks via Inngest workflows.
– Authentication Middleware: Clerk integration via middleware.js and app/(auth) routes.
– Database Layer: Prisma ORM abstracts Postgres schema and migrations.

##### Relevant Technologies to Call Out
– Next.js 15 (App Router, Server & Client Components)
– React 18 + Shadcn UI + Tailwind CSS
– Clerk for authentication
– Prisma ORM + Neon DB (Postgres)
– Inngest for background jobs
– Google Generative AI (Gemini) for AI features
– Vercel for Hosting & Serverless Functions

##### Things to Emphasize
– The separation of concerns between UI, API, jobs, and data storage
– How Clerk sits between user and Next.js for auth
– The two pathways for AI tasks: synchronous (via Server Action) vs asynchronous (via Inngest)
– Prisma as single source of truth for data model and migrations
– The flow of environment‑driven configuration (env vars for Clerk, Gemini, Database)

Putting It All Together

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser UI)" 
        direction TB
        Browser["Browser UI"]:::ui
        Static["Static Assets\n(public/, globals.css, tailwind.config.mjs)"]:::ui
    end

    %% Frontend Next.js App Router
    subgraph "Frontend Next.js\n(App Router)" 
        direction TB
        Layout["app/layout.js"]:::frontend
        Page["app/page.js"]:::frontend
        AuthRoutes["app/(auth)/"]:::frontend
        MainRoutes["app/(main)/"]:::frontend
        UIComp["components/ui/"]:::ui
        Middleware["middleware.js"]:::frontend
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        NextApi["app/api/inngest/route.js"]:::api
        Actions["actions/*.js"]:::api
    end

    %% Business Logic & Utilities
    subgraph "Business Logic & Utilities"
        direction TB
        Helper["app/lib/helper.js"]:::util
        SchemaLib["app/lib/schema.js"]:::util
        Utils["lib/utils.js"]:::util
        CheckUser["lib/checkUser.js"]:::util
        UseFetch["hooks/use-fetch.js"]:::util
    end

    %% Background Job Processor
    subgraph "Background Job Processor\n(Inngest)" 
        direction TB
        InngestClient["lib/inngest/client.js"]:::jobs
        InngestFunc["lib/inngest/function.js"]:::jobs
    end

    %% Database Layer
    subgraph "Database (Neon DB + Prisma)"
        direction TB
        PrismaSchema["prisma/schema.prisma"]:::storage
        Migrations["prisma/migrations/"]:::storage
        PrismaClient["lib/prisma.js"]:::storage
        NeonDB[(Neon DB)]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth Service"]:::external
        Gemini["Google Gemini API"]:::external
    end

    %% Hosting / Orchestration
    subgraph "Hosting / Orchestration"
        direction TB
        NextConfig["next.config.mjs"]:::frontend
    end

    %% Connections
    Browser -->|requests pages| Layout
    Browser -->|requests pages| Page
    Browser -->|static assets| Static
    Layout -->|renders| UIComp
    Page -->|uses| UIComp
    Browser -->|auth flows| AuthRoutes
    AuthRoutes -->|calls| Clerk
    Middleware -->|protects routes| AuthRoutes
    Page -->|server actions/API| NextApi
    Page -->|server actions| Actions
    NextApi -->|enqueue jobs| InngestClient
    Actions -->|business logic| Helper
    Actions -->|data operations| PrismaClient
    Actions -->|async AI tasks| InngestClient
    Actions -->|sync AI tasks| Gemini
    InngestClient -->|triggers| InngestFunc
    InngestFunc -->|db read/write| PrismaClient
    InngestFunc -->|AI calls| Gemini
    PrismaClient -->|CRUD| NeonDB
    Helper -->|utils| Utils
    Helper -->|schema validation| SchemaLib
    Utils -->|auth check| CheckUser
    Page -->|data fetch| UseFetch
    NextApi -->|db operations| PrismaClient
    NextApi -->|jobs| InngestClient
    NextConfig -->|configures| Layout

    %% Click Events
    click Browser "https://github.com/uday-4083/evolvai/tree/main/components/"
    click Static "https://github.com/uday-4083/evolvai/tree/main/public/"
    click Layout "https://github.com/uday-4083/evolvai/blob/main/app/layout.js"
    click Page "https://github.com/uday-4083/evolvai/blob/main/app/page.js"
    click AuthRoutes "https://github.com/uday-4083/evolvai/tree/main/app/(auth)/"
    click MainRoutes "https://github.com/uday-4083/evolvai/tree/main/app/(main)/"
    click UIComp "https://github.com/uday-4083/evolvai/tree/main/components/ui/"
    click Middleware "https://github.com/uday-4083/evolvai/blob/main/middleware.js"
    click NextApi "https://github.com/uday-4083/evolvai/blob/main/app/api/inngest/route.js"
    click Actions "https://github.com/uday-4083/evolvai/tree/main/actions/"
    click Helper "https://github.com/uday-4083/evolvai/blob/main/app/lib/helper.js"
    click SchemaLib "https://github.com/uday-4083/evolvai/blob/main/app/lib/schema.js"
    click Utils "https://github.com/uday-4083/evolvai/blob/main/lib/utils.js"
    click CheckUser "https://github.com/uday-4083/evolvai/blob/main/lib/checkUser.js"
    click UseFetch "https://github.com/uday-4083/evolvai/blob/main/hooks/use-fetch.js"
    click InngestClient "https://github.com/uday-4083/evolvai/blob/main/lib/inngest/client.js"
    click InngestFunc "https://github.com/uday-4083/evolvai/blob/main/lib/inngest/function.js"
    click PrismaSchema "https://github.com/uday-4083/evolvai/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/uday-4083/evolvai/tree/main/prisma/migrations/"
    click PrismaClient "https://github.com/uday-4083/evolvai/blob/main/lib/prisma.js"
    click NextConfig "https://github.com/uday-4083/evolvai/blob/main/next.config.mjs"

    %% Styles
    classDef ui fill:#D6EFFF,stroke:#0366D6,color:#0366D6;
    classDef frontend fill:#DFF7DF,stroke:#28A745,color:#28A745;
    classDef api fill:#FFF4E5,stroke:#FD7E14,color:#FD7E14;
    classDef util fill:#F0ECFF,stroke:#6F42C1,color:#6F42C1;
    classDef jobs fill:#FFEEF0,stroke:#CB2431,color:#CB2431;
    classDef storage fill:#FFF5D1,stroke:#E36209,color:#E36209;
    classDef external fill:#EAEAEA,stroke:#6A737D,color:#6A737D;
```
