# vincanger/coverlettergpt architecture

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

- Interactive diagram: https://gitdiagram.com/vincanger/coverlettergpt
- Repository: https://github.com/vincanger/coverlettergpt

## Overview

##### Project Type and Purpose
- This is a full-stack web application called CoverLetterGPT.xyz built with Wasp.
- Purpose: let users generate custom cover letters using OpenAI’s GPT models, manage subscriptions (Stripe + Bitcoin Lightning), and notify them before renewal via email.

##### File Structure Highlights
- Root
- `main.wasp`: Wasp config describing entities, auth, UI routes, server actions
- `schema.prisma` + `migrations/`: database schema and evolution scripts
- `env.server.example`: environment variables (DB URL, API keys)
- `src/client/`: React + Chakra UI pages and reusable components
- `src/server/`: server-side logic
- `actions.ts`: OpenAI prompts and generation logic
- `auth.ts`: Google OAuth and session management
- `ln.ts`: Lightning invoice creation and payment status
- `webhooks.ts`: receiving Stripe and LN updates
- `workers/`: scheduled tasks (email reminders via SendGrid)
- Shared utilities under `src/shared/`

##### Key Components
- Frontend (browser)
- React app served by Vite (port 3000)
- Chakra UI for styling
- Calls backend via HTTP REST endpoints (Wasp actions & queries)
- Backend (Node/Express under the hood)
- Wasp-generated Express server (port 3001)
- Defines endpoints for auth, cover-letter generation, payments, and webhooks
- Uses Prisma client for DB access
- Database
- PostgreSQL instance (Docker or external)
- Tables for Users, CoverLetters, Payments, Subscriptions, etc.
- External Services
- OpenAI API (GPT-4o or GPT-3.5)
- Stripe API (subscription management, checkout sessions)
- Bitcoin Lightning (Bolt11 invoices, status polling via webhooks)
- SendGrid (email reminders)
- Worker / Scheduler
- Cron job in `src/server/workers/updateUserSubscription.ts`
- Runs periodically to send renewal notifications
- Wasp Framework
- Glue layer that wires the above pieces together based on `main.wasp`

##### Relationships and Data Flow
- User → Browser → React UI
- UI → HTTP → Wasp/Express server
- Server ←→ Prisma ←→ PostgreSQL
- Server → OpenAI / Stripe / Lightning / SendGrid
- External webhooks (Stripe, Lightning) → Server’s webhook endpoints
- Scheduler Worker → Server code → Database & SendGrid

##### Architectural Patterns & Principles
- Monorepo with clear client/server separation
- Declarative full-stack setup via Wasp config
- API-driven server functions (actions/queries)
- Event-driven webhooks and scheduled workers for asynchronous tasks
- Single source of truth for schema via Prisma

##### Final Checklist
- A note calling out `main.wasp` as the declarative glue

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    MW["main.wasp"]:::config

    %% Frontend Layer
    subgraph "Frontend (React App, port 3000)" 
        direction TB
        App["App.tsx"]:::ui
        ClientSetup["clientSetup.ts"]:::ui
        subgraph "Pages"
            direction TB
            MainPage["MainPage.tsx"]:::ui
            LoginPage["LoginPage.tsx"]:::ui
            CheckoutPage["CheckoutPage.tsx"]:::ui
            CoverLetterPage["CoverLetterPage.tsx"]:::ui
            JobsPage["JobsPage.tsx"]:::ui
            ProfilePage["ProfilePage.tsx"]:::ui
        end
        subgraph "Theme & Styling"
            direction TB
            ThemeIndex["index.ts"]:::ui
            ThemeTokens["tokens.ts"]:::ui
            ThemeText["text.ts"]:::ui
        end
        subgraph "Components"
            direction TB
            NavBar["NavBar.tsx"]:::ui
            AlertDialog["AlertDialog.tsx"]:::ui
            Modal["Modal.tsx"]:::ui
            LnPaymentModal["LnPaymentModal.tsx"]:::ui
            CreativitySlider["CreativitySlider.tsx"]:::ui
            ComponentsDir["src/client/components/"]:::ui
        end
        LightningUtils["lightningUtils.ts"]:::ui
    end

    %% Backend Layer
    subgraph "Backend (Express Server, port 3001)" 
        direction TB
        Actions["actions.ts"]:::backend
        Queries["queries.ts"]:::backend
        Auth["auth.ts"]:::backend
        LNServer["ln.ts"]:::backend
        Webhooks["webhooks.ts"]:::backend
    end

    %% Worker
    subgraph "Worker (Cron Scheduler)" 
        direction TB
        UpdateSub["updateUserSubscription.ts"]:::worker
    end

    %% Database
    DB["PostgreSQL"]:::db
    Schema["schema.prisma"]:::db
    Migrations["migrations/"]:::db

    %% Shared Utilities
    SharedUtils["utils.ts"]:::shared

    %% External Services
    subgraph "External Services" 
        direction TB
        OpenAI["OpenAI API"]:::service
        Stripe["Stripe API"]:::service
        LightningExt["Bitcoin Lightning"]:::service
        SendGrid["SendGrid"]:::service
    end

    %% Connections
    MW -->|"generates code for"| App
    MW -->|"generates code for"| Actions

    App -->|"HTTP REST"| Actions
    ClientSetup -->|"bundles via Vite"| App

    Actions -->|"Prisma Client"| DB
    Queries -->|"Prisma Client"| DB

    Actions -->|"calls OpenAI"| OpenAI
    Actions -->|"creates checkout"| Stripe
    LNServer -->|"creates invoices"| LightningExt
    Actions -->|"sends emails"| SendGrid

    Stripe -->|"webhook POST"| Webhooks
    LightningExt -->|"webhook POST"| Webhooks
    Webhooks -->|"updates"| DB

    UpdateSub -->|"Cron"| UpdateSub
    UpdateSub -->|"reads/writes"| DB
    UpdateSub -->|"sends reminders"| SendGrid

    SharedUtils --> Actions
    SharedUtils --> Queries
    SharedUtils --> UpdateSub
    SharedUtils --> App

    Schema --> DB
    Migrations --> DB

    %% Click Events
    click MW "https://github.com/vincanger/coverlettergpt/blob/main/main.wasp"
    click Schema "https://github.com/vincanger/coverlettergpt/blob/main/schema.prisma"
    click Migrations "https://github.com/vincanger/coverlettergpt/tree/main/migrations/"
    click App "https://github.com/vincanger/coverlettergpt/blob/main/src/client/App.tsx"
    click ClientSetup "https://github.com/vincanger/coverlettergpt/blob/main/src/client/clientSetup.ts"
    click ThemeIndex "https://github.com/vincanger/coverlettergpt/blob/main/src/client/theme/index.ts"
    click ThemeTokens "https://github.com/vincanger/coverlettergpt/blob/main/src/client/theme/tokens.ts"
    click ThemeText "https://github.com/vincanger/coverlettergpt/blob/main/src/client/theme/text.ts"
    click MainPage "https://github.com/vincanger/coverlettergpt/blob/main/src/client/MainPage.tsx"
    click LoginPage "https://github.com/vincanger/coverlettergpt/blob/main/src/client/LoginPage.tsx"
    click CheckoutPage "https://github.com/vincanger/coverlettergpt/blob/main/src/client/CheckoutPage.tsx"
    click CoverLetterPage "https://github.com/vincanger/coverlettergpt/blob/main/src/client/CoverLetterPage.tsx"
    click JobsPage "https://github.com/vincanger/coverlettergpt/blob/main/src/client/JobsPage.tsx"
    click ProfilePage "https://github.com/vincanger/coverlettergpt/blob/main/src/client/ProfilePage.tsx"
    click NavBar "https://github.com/vincanger/coverlettergpt/blob/main/src/client/components/NavBar.tsx"
    click AlertDialog "https://github.com/vincanger/coverlettergpt/blob/main/src/client/components/AlertDialog.tsx"
    click Modal "https://github.com/vincanger/coverlettergpt/blob/main/src/client/components/Modal.tsx"
    click LnPaymentModal "https://github.com/vincanger/coverlettergpt/blob/main/src/client/components/LnPaymentModal.tsx"
    click CreativitySlider "https://github.com/vincanger/coverlettergpt/blob/main/src/client/components/CreativitySlider.tsx"
    click ComponentsDir "https://github.com/vincanger/coverlettergpt/tree/main/src/client/components/"
    click LightningUtils "https://github.com/vincanger/coverlettergpt/blob/main/src/client/lightningUtils.ts"
    click Actions "https://github.com/vincanger/coverlettergpt/blob/main/src/server/actions.ts"
    click Queries "https://github.com/vincanger/coverlettergpt/blob/main/src/server/queries.ts"
    click Auth "https://github.com/vincanger/coverlettergpt/blob/main/src/server/auth.ts"
    click LNServer "https://github.com/vincanger/coverlettergpt/blob/main/src/server/ln.ts"
    click Webhooks "https://github.com/vincanger/coverlettergpt/blob/main/src/server/webhooks.ts"
    click UpdateSub "https://github.com/vincanger/coverlettergpt/blob/main/src/server/workers/updateUserSubscription.ts"
    click SharedUtils "https://github.com/vincanger/coverlettergpt/blob/main/src/shared/utils.ts"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#4285F4,stroke-width:2px
    classDef backend fill:#D6F5D6,stroke:#34A853,stroke-width:2px
    classDef db fill:#FFE5B4,stroke:#FB8C00,stroke-width:2px
    classDef service fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px
    classDef worker fill:#D0F2F1,stroke:#009688,stroke-width:2px
    classDef config fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px
    classDef shared fill:#F0F0F0,stroke:#666666,stroke-width:2px
```
