# piyush-eon/ai-career-coach architecture

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

- Interactive diagram: https://gitdiagram.com/piyush-eon/ai-career-coach
- Repository: https://github.com/piyush-eon/ai-career-coach

## Overview

##### Project Type and Purpose
- This is a full‑stack AI‑powered career coaching web application built with Next.js (App Router), Tailwind CSS, Prisma ORM, Neon DB, Inngest for background/event workflows, Clerk for authentication, and Shadcn UI components.
- It provides user authentication, onboarding, AI‑driven resume and cover‑letter generation (via Gemini API), practice quizzes/interviews, and dashboards.

##### Main Components
a. Frontend (Next.js “app” directory)
– Public pages: landing, auth pages (sign‑in, sign‑up), onboarding, dashboard, AI cover‑letter, resume builder, interview mock quizzes.
– UI layer: Shadcn UI components under components/ui, plus shared components (header, hero).
– CSS: Tailwind (tailwind.config.mjs, globals.css).
b. Backend/API
– Next.js API routes (app/api) for synchronous calls.
– Inngest functions (lib/inngest and app/api/inngest) for asynchronous jobs and event‑driven workflows (e.g., generating AI content).
– Helper libraries: app/lib (helper.js, schema.js), lib/utils, lib/checkUser.
c. Authentication & Authorization
– Clerk (third‑party auth) configuration via environment variables and middleware.js to guard routes.
d. Database & ORM
– Neon Postgres, accessed via Prisma (prisma/schema.prisma & prisma/migrations).
e. External Services
– Gemini AI API for text generation.
– Clerk.io for user sign‑in/up flows.

##### Relationships and Data Flows
- User’s browser ↔ Next.js front end pages (UI components).
- Front end → Clerk (OAuth flows) → Protected content.
- Authenticated front end → Next.js API or Inngest endpoints → Business logic in JS modules.
- API/Inngest handlers → Prisma client → Neon DB for reads/writes.
- Inngest jobs → Gemini API calls → store/generated content in DB → notify front end.

##### Architectural Patterns and Design Principles
- App Router pattern (Next.js 13) for file‑based routing and layouts.
- Separation of concerns: UI components, page logic, API routes, background workers.
- Event‑driven background processing via Inngest for long‑running AI tasks.
- 12‑factor app principles: environment variables, clear config files.
- Modular, reusable UI via Shadcn components.

##### Technologies and Frameworks to Annotate
– Next.js App Router
– Tailwind CSS
– Shadcn UI components
– Prisma ORM / Neon Postgres
– Inngest (event queue/workflow runner)
– Clerk (authentication)
– Gemini API (AI service)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser / Client"]:::client
        subgraph "Next.js Frontend (App Router)" 
            signIn["Sign‑In Page"]:::frontend
            signUp["Sign‑Up Page"]:::frontend
            onboarding["Onboarding Page"]:::frontend
            dashboard["Dashboard Page"]:::frontend
            aiCover["AI Cover‑Letter Pages"]:::frontend
            resumePage["Resume Builder Page"]:::frontend
            interview["Interview Pages"]:::frontend
            subgraph "UI Components" 
                uiComponents["components/ui/*"]:::frontend
            end
            header["Header"]:::frontend
            hero["Hero"]:::frontend
            themeProvider["Theme Provider"]:::frontend
            rootLayout["Root Layout"]:::frontend
            mainLayout["Main Layout"]:::frontend
            authLayout["Auth Layout"]:::frontend
            tailwindConfig["tailwind.config.mjs"]:::frontend
            postcssConfig["postcss.config.mjs"]:::frontend
            globalsCSS["globals.css"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer"
        APIRoutes["Next.js API Routes"]:::api
        InngestFuncs["Inngest Functions"]:::api
        subgraph "Helper Libraries & Middleware"
            helper["helper.js"]:::api
            schemaLib["schema.js"]:::api
            utils["utils.js"]:::api
            checkUser["checkUser.js"]:::api
            middleware["middleware.js"]:::api
        end
        subgraph "Business Logic Actions"
            coverLetter["cover-letter.js"]:::api
            resumeAction["resume.js"]:::api
            interviewAction["interview.js"]:::api
            dashboardAction["dashboard.js"]:::api
            userAction["user.js"]:::api
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        PrismaClient["Prisma Client"]:::db
        NeonDB["Neon Postgres"]:::db
        prismaSchema["schema.prisma"]:::db
        prismaMigrations["prisma/migrations/*"]:::db
        prismaLib["lib/prisma.js"]:::db
    end

    %% External Services
    subgraph "External Services"
        Clerk["Clerk Auth"]:::external
        Gemini["Gemini AI"]:::external
    end

    %% Connections
    Browser -->|"HTTP"| signIn
    Browser -->|"HTTP"| signUp
    Browser -->|"HTTP"| onboarding
    Browser -->|"HTTP"| dashboard
    Browser -->|"HTTP"| aiCover
    Browser -->|"HTTP"| resumePage
    Browser -->|"HTTP"| interview

    signIn -->|"uses UI"| uiComponents
    signUp -->|"uses UI"| uiComponents
    onboarding -->|"uses UI"| uiComponents
    dashboard -->|"uses UI"| uiComponents
    aiCover -->|"uses UI"| uiComponents
    resumePage -->|"uses UI"| uiComponents
    interview -->|"uses UI"| uiComponents

    signIn -->|"layout"| authLayout
    signUp --> authLayout
    onboarding --> mainLayout
    dashboard --> mainLayout
    aiCover --> mainLayout
    resumePage --> mainLayout
    interview --> mainLayout

    signIn -->|"Auth OAuth"| Clerk
    signUp --> Clerk

    onboarding -->|"REST call"| APIRoutes
    dashboard --> APIRoutes
    aiCover --> APIRoutes
    resumePage --> APIRoutes
    interview --> APIRoutes

    signIn --> middleware
    signUp --> middleware

    APIRoutes --> helper
    APIRoutes --> schemaLib
    APIRoutes --> utils
    APIRoutes --> checkUser
    APIRoutes --> coverLetter
    APIRoutes --> resumeAction
    APIRoutes --> interviewAction
    APIRoutes --> dashboardAction
    APIRoutes --> userAction
    APIRoutes --> PrismaClient
    APIRoutes --> NeonDB

    InngestFuncs --> prismaLib
    InngestFuncs --> PrismaClient
    InngestFuncs --> NeonDB
    InngestFuncs --> Gemini

    coverLetter --> PrismaClient
    resumeAction --> PrismaClient
    interviewAction --> PrismaClient
    dashboardAction --> PrismaClient
    userAction --> PrismaClient

    PrismaClient --> prismaSchema
    PrismaClient --> prismaMigrations
    PrismaClient --> NeonDB

    %% Click events
    click signIn "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(auth)/sign-in/[[...sign-in]]/page.jsx"
    click signUp "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(auth)/sign-up/[[...sign-up]]/page.jsx"
    click onboarding "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/onboarding/page.jsx"
    click dashboard "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/dashboard/page.jsx"
    click aiCover "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/ai-cover-letter/page.jsx"
    click aiCover "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/ai-cover-letter/[id]/page.jsx"
    click resumePage "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/resume/page.jsx"
    click interview "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/interview/page.jsx"
    click interview "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/interview/mock/page.jsx"
    click uiComponents "https://github.com/piyush-eon/ai-career-coach/tree/master/components/ui/"
    click header "https://github.com/piyush-eon/ai-career-coach/blob/master/components/header.jsx"
    click hero "https://github.com/piyush-eon/ai-career-coach/blob/master/components/hero.jsx"
    click themeProvider "https://github.com/piyush-eon/ai-career-coach/blob/master/components/theme-provider.jsx"
    click rootLayout "https://github.com/piyush-eon/ai-career-coach/blob/master/app/layout.js"
    click mainLayout "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(main)/layout.jsx"
    click authLayout "https://github.com/piyush-eon/ai-career-coach/blob/master/app/(auth)/layout.js"
    click tailwindConfig "https://github.com/piyush-eon/ai-career-coach/blob/master/tailwind.config.mjs"
    click postcssConfig "https://github.com/piyush-eon/ai-career-coach/blob/master/postcss.config.mjs"
    click globalsCSS "https://github.com/piyush-eon/ai-career-coach/blob/master/app/globals.css"
    click APIRoutes "https://github.com/piyush-eon/ai-career-coach/blob/master/app/api/inngest/route.js"
    click helper "https://github.com/piyush-eon/ai-career-coach/blob/master/app/lib/helper.js"
    click schemaLib "https://github.com/piyush-eon/ai-career-coach/blob/master/app/lib/schema.js"
    click utils "https://github.com/piyush-eon/ai-career-coach/blob/master/lib/utils.js"
    click checkUser "https://github.com/piyush-eon/ai-career-coach/blob/master/lib/checkUser.js"
    click middleware "https://github.com/piyush-eon/ai-career-coach/blob/master/middleware.js"
    click prismaSchema "https://github.com/piyush-eon/ai-career-coach/blob/master/prisma/schema.prisma"
    click prismaMigrations "https://github.com/piyush-eon/ai-career-coach/tree/master/prisma/migrations/"
    click prismaLib "https://github.com/piyush-eon/ai-career-coach/blob/master/lib/prisma.js"
    click coverLetter "https://github.com/piyush-eon/ai-career-coach/blob/master/actions/cover-letter.js"
    click resumeAction "https://github.com/piyush-eon/ai-career-coach/blob/master/actions/resume.js"
    click interviewAction "https://github.com/piyush-eon/ai-career-coach/blob/master/actions/interview.js"
    click dashboardAction "https://github.com/piyush-eon/ai-career-coach/blob/master/actions/dashboard.js"
    click userAction "https://github.com/piyush-eon/ai-career-coach/blob/master/actions/user.js"
    classDef frontend fill:#E0F2FE,stroke:#0284C7,color:#0369A1;
    classDef api fill:#ECFDF5,stroke:#10B981,color:#059669;
    classDef db fill:#FFFBEB,stroke:#F59E0B,color:#B45309;
    classDef external fill:#F3F4F6,stroke:#6B7280,color:#4B5563;
    classDef client fill:#EDE9FE,stroke:#A78BFA,color:#7C3AED;
```
