# jagan-shanmugam/cover-coach architecture

> Architecture diagram of the GitHub repository jagan-shanmugam/cover-coach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jagan-shanmugam/cover-coach
- Repository: https://github.com/jagan-shanmugam/cover-coach

## Overview

##### Main Components Identification
- Frontend: Represented by the Next.js application in the “src/app” directory with various pages (cover letters, CV builder, interview prep, job postings, etc.) and reusable UI components in “src/components” and “src/hooks”.
- Backend API Endpoints: Highlight API routes under “src/app/api” such as “/api/llm” (LLM interactions), “/api/scrape-job” (job scraping), “/api/customize-letter” (cover letter customization), etc.
- Database & Authentication: A Supabase backend is used, with PostgreSQL as the database containing core tables (job postings, documents, applications, CV details, etc.). Security via Row Level Security (RLS) and additional configurations via SQL scripts in the “scripts” directory should be noted.
- External Services and Integrations: Include external AI providers (OpenAI, DeepInfra, Perplexity, etc.), Brevo for transactional emails, and job board integrations (Arbeitnow, Findwork). These should be shown as connected to the relevant API endpoints or backend service.
- Additional Utilities & Helpers: The project also has a set of libraries (e.g., job scraping utilities, PDF template generation, and custom templates for cover letters/CVs), configuration files (ESLint, Tailwind, TypeScript), and middleware.

##### Relationships and Interactions
- Clear data flows: For example, the user interacts with the Next.js frontend which communicates with various API endpoints for AI services, job scraping, or PDF generation.
- Connection to Supabase: Indicate that API routes and authentication mechanisms in the frontend rely on Supabase for database operations, user management, and security policies (RLS).
- CI/CD Flow: Include flow from code commit → GitHub Actions (show branches “main” for production and PRs for preview) → Vercel deployment → monitoring and notifications.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clearly show the split between the UI (frontend), API (backend logic), and database layers.
- API-First Design: Illustrate that the API endpoints encapsulate core business logic and integrate with external AI/ML services.
- Component-Based UI: Highlight the modularity (reusable components for cover letters, CVs, interview prep, etc.).
- Serverless/API Routes: Emphasize that many backend functionalities are implemented as serverless endpoints using Next.js routing.
- Security: Represent integration with Supabase’s secure authentication and RLS, as well as the careful handling of environment configurations.

##### Technologies, Frameworks, and Libraries
- Frontend: Next.js 15, TypeScript, Tailwind CSS, shadcn UI, Framer Motion.
- Backend: Next.js API routes, Supabase (PostgreSQL, authentication, RLS), Node.js.
- AI/ML: LangChain with multiple LLM providers (OpenAI, DeepInfra, Perplexity, etc.).
- Deployment & CI/CD: Vercel, GitHub Actions (including production and preview workflows), ESLint.
- Database: PostgreSQL with several SQL scripts to set up tables and migration logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    U("User"):::external

    %% Frontend Section
    subgraph "Frontend"
        direction TB
        FE["Next.js Frontend"]:::frontend
        UI["Pages & Layouts (/src/app)"]:::frontend
        CP["Reusable UI Components (/src/components & /src/hooks)"]:::frontend
    end

    %% Backend API Section
    subgraph "Backend API"
        direction TB
        API["API Endpoints (/src/app/api)"]:::api
        LLM["LLM API (/api/llm)"]:::api
        JS["Job Scraping (/api/scrape-job & /api/scrape)"]:::api
        CL["Cover Letter Customization (/api/customize-letter)"]:::api
        PDF["PDF Generation (/api/generate-pdf)"]:::api
        INT["Interview Prep (/api/interview-prep & /api/interview-chat)"]:::api
        ARB["Job Board Integration (ArbeitNow)"]:::api
        CRON["Cron Tasks (/api/cron/sync-jobs)"]:::api
    end

    %% Database & Authentication (Supabase)
    subgraph "Database & Authentication"
        direction TB
        DB["Supabase Database"]:::database
        SQL["SQL Scripts (tables & RLS)"]:::database
        SUP["Supabase Utils & Config"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        EXTAI["External AI Providers & Job APIs"]:::external
        EMAIL["Email Service (Brevo)"]:::external
    end

    %% CI/CD and Deployment
    subgraph "CI/CD and Deployment"
        direction TB
        GHA["GitHub Actions Workflows"]:::cicd
        VERCEL["Vercel Deployment"]:::cicd
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        direction TB
        PDFTMP["PDF & Templates Library"]:::utils
        JOBUTIL["Job Scraping Utilities"]:::utils
        CONFIG["Configuration Files (ESLint, Tailwind, TS)"]:::utils
        MID["Middleware"]:::utils
    end

    %% Relationships
    U -->|"visits"| FE
    FE -->|"renders"| UI
    FE -->|"composes"| CP
    FE -->|"calls"| API

    API -->|"reads/writes"| DB
    API -->|"utilizes"| SUP
    API -->|"executes"| SQL
    API -->|"integrates"| EXTAI
    API -->|"triggers"| EMAIL

    API -->|"contains"| LLM
    API -->|"contains"| JS
    API -->|"contains"| CL
    API -->|"contains"| PDF
    API -->|"contains"| INT
    API -->|"contains"| ARB
    API -->|"contains"| CRON

    FE -->|"assisted by"| CONFIG
    FE -->|"enhanced by"| MID
    API -->|"uses"| PDFTMP
    API -->|"uses"| JOBUTIL

    GHA -->|"deploys to"| VERCEL
    FE -->|"updates"| VERCEL

    %% Click Events for Frontend
    click UI "https://github.com/jagan-shanmugam/cover-coach/tree/main/src/app"
    click CP "https://github.com/jagan-shanmugam/cover-coach/tree/main/src/components"
    click CP "https://github.com/jagan-shanmugam/cover-coach/tree/main/src/hooks"

    %% Click Events for Backend API Endpoints
    click LLM "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/llm/route.ts"
    click JS "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/scrape-job/route.ts"
    click JS "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/scrape/route.ts"
    click JS "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/scrape/scrapers.ts"
    click CL "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/customize-letter/route.ts"
    click CL "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/customize-letter/customize-cover-letter.ts"
    click PDF "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/generate-pdf/route.ts"
    click INT "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/interview-prep/route.ts"
    click INT "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/interview-chat/route.ts"
    click ARB "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/arbeit-now/route.ts"
    click CRON "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/app/api/cron/sync-jobs/route.ts"

    %% Click Events for Database & Authentication
    click SQL "https://github.com/jagan-shanmugam/cover-coach/blob/main/scripts/create_tables.sql"
    click SQL "https://github.com/jagan-shanmugam/cover-coach/blob/main/scripts/enforce_rls.sql"
    click SUP "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/utils/supabase.ts"
    click SUP "https://github.com/jagan-shanmugam/cover-coach/blob/main/supabase/config.toml"
    click SUP "https://github.com/jagan-shanmugam/cover-coach/tree/main/supabase/functions/sync-jobs"

    %% Click Events for CI/CD and Deployment
    click GHA "https://github.com/jagan-shanmugam/cover-coach/blob/main/.github/workflows/preview.yml"
    click GHA "https://github.com/jagan-shanmugam/cover-coach/blob/main/.github/workflows/production.yml"
    click VERCEL "https://github.com/jagan-shanmugam/cover-coach/blob/main/vercel.json"
    click VERCEL "https://github.com/jagan-shanmugam/cover-coach/blob/main/next.config.ts"

    %% Click Events for Utilities & Helpers
    click PDFTMP "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/lib/pdf-template.ts"
    click PDFTMP "https://github.com/jagan-shanmugam/cover-coach/tree/main/src/lib/templates"
    click JOBUTIL "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/lib/job-scraper.ts"
    click CONFIG "https://github.com/jagan-shanmugam/cover-coach/blob/main/eslint.config.mjs"
    click CONFIG "https://github.com/jagan-shanmugam/cover-coach/blob/main/tailwind.config.js"
    click CONFIG "https://github.com/jagan-shanmugam/cover-coach/blob/main/tsconfig.json"
    click MID "https://github.com/jagan-shanmugam/cover-coach/blob/main/src/middleware.ts"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1976d2,stroke-width:2px;
    classDef api fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef database fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef external fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px;
    classDef cicd fill:#e1bee7,stroke:#7b1fa2,stroke-width:2px;
    classDef utils fill:#b2dfdb,stroke:#00796b,stroke-width:2px;
    classDef external fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px;
```
