# adrianhajdin/saas-app architecture

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

- Interactive diagram: https://gitdiagram.com/adrianhajdin/saas-app
- Repository: https://github.com/adrianhajdin/saas-app

## Overview

##### Project type and purpose
- This is a full-stack SaaS LMS (Learning Management System) web application built with Next.js (app directory, server-components, API routes), TypeScript, Tailwind CSS, shadcn/ui.
- It integrates authentication & billing (Clerk & Stripe), real-time DB (Supabase), AI voice agents (Vapi), and monitoring (Sentry).

##### File structure
- **app/** — Next.js 13 “app router”: pages (e.g., /companions, /my-journey), API routes under app/api/sentry-example-api/route.ts
- **components/** — React UI components and shadcn/ui primitives
- **lib/** — service clients and action handlers (lib/supabase.ts, lib/vapi.sdk.ts, lib/actions)
- **instrumentation.ts / instrumentation-client.ts** — Sentry error & performance instrumentation
- **constants/** & **types/** — shared configs and TypeScript types
- **middleware.ts** — Next.js middleware for auth/session checks
- **next.config.ts**, **sentry.edge.server.config.ts**, **sentry.server.config.ts** — build and monitoring configs
- **public/** — static assets for UI and README images

##### README for additional insights
- Tech stack calls out Clerk (auth & billing), Next.js, Sentry, shadcn/ui, Supabase (PostgreSQL, real-time), Tailwind, TypeScript, Vapi (voice AI).
- Features: AI voice tutoring (Vapi), subscription management (Clerk + Stripe), bookmarks, session history (Supabase).

a. Main components
- Client (Browser/React)
- Next.js Server (SSR, SSG, API Routes)
- PostgreSQL Database (Supabase)
- Authentication & Billing Service (Clerk + Stripe)
- AI Voice Service (Vapi)
- Monitoring & Error Tracking (Sentry)
- Static Assets (CDN / public folder)

b. Relationships & interactions
1. Client ↔ Next.js Server
- UI pages & components rendered (React + shadcn/ui)
- Fetch data via built-in fetch/React server components and client components
2. Next.js Server → Supabase
- CRUD operations (sessions, bookmarks, companions) via lib/supabase.ts
- Real-time subscriptions for live updates
3. Next.js Server → Clerk
- User authentication and session validation (middleware.ts)
- Subscription plan lookup / billing flows (via Clerk API + Stripe)
4. Next.js Server ↔ Vapi
- Voice requests: speech-to-text, text-to-speech, conversational AI
- Handled in lib/vapi.sdk.ts and companion actions
5. Next.js Server → Sentry
- Server-side error/performance events (sentry.server.config.ts)
- Client-side instrumentation (instrumentation-client.ts)
6. Next.js Server → CDN (public/)

c. Architectural patterns & design principles
- **Component-based UI** (React + shadcn/ui)
- **Separation of concerns**: UI vs. API vs. services
- **Server-components** and **client-components** pattern in Next.js
- **Middleware** for auth gating
- **SDK wrapper layer** (lib/vapi, lib/supabase) for external services
- **Edge/server distinction** for Sentry (edge vs. server config)

d. Key technologies
- Frontend: Next.js 13 (app router), React, Tailwind CSS, shadcn/ui
- Backend: Next.js API routes, TypeScript
- DB: Supabase (PostgreSQL, real-time)
- Auth/Billing: Clerk + Stripe
- AI: Vapi Voice AI SDK
- Monitoring: Sentry
- Validation: Zod (in API handlers)

##### Detail
- Middleware.ts (auth guard)
- app/api routes (sentry-example-api, etc.)
- lib/actions (companion.actions.ts)
- instrumentation modules
- How UI components (Navbar, CompanionCard, SearchInput) fetch data via Next.js data layer.
- Subscription flow: Client → Clerk Checkout → Clerk Webhook → Next.js API → Supabase update.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Zone
    subgraph "Client (Browser)"
        direction TB
        CTA["CTA Component"]:::component
        CompanionCard["CompanionCard Component"]:::component
        CompanionComponent["CompanionComponent Component"]:::component
        CompanionForm["CompanionForm Component"]:::component
        CompanionsList["CompanionsList Component"]:::component
        Navbar["Navbar Component"]:::component
        SearchInput["SearchInput Component"]:::component
        SubjectFilter["SubjectFilter Component"]:::component
        UIPrimitives["shadcn/ui Primitives"]:::component
        InstrumentationClient["Client-Side Sentry Instrumentation"]:::monitoring
    end

    %% Server Zone
    subgraph "Next.js Server" 
        direction TB
        Middleware["middleware.ts"]:::server
        subgraph "App Pages & Layout"
            direction TB
            Layout["app/layout.tsx"]:::server
            GlobalsCSS["app/globals.css"]:::server
            PageRoot["app/page.tsx"]:::server
            CompanionsListPage["app/companions/page.tsx"]:::server
            CompanionDetailPage["app/companions/[id]/page.tsx"]:::server
            CompanionNewPage["app/companions/new/page.tsx"]:::server
            MyJourney["app/my-journey/page.tsx"]:::server
            SubscriptionPage["app/subscription/page.tsx"]:::server
            SignInPage["app/sign-in/[[...sign-in]]/page.tsx"]:::server
            GlobalError["app/global-error.tsx"]:::server
        end
        APIRoutes["app/api/sentry-example-api/route.ts"]:::server
        subgraph "Service Wrappers"
            direction TB
            SupabaseClient["lib/supabase.ts"]:::service
            VapiSDK["lib/vapi.sdk.ts"]:::service
            CompanionActions["lib/actions/companion.actions.ts"]:::service
            Constants["constants/index.ts"]:::server
            Soundwaves["constants/soundwaves.json"]:::server
            TypesIndex["types/index.d.ts"]:::server
            TypesVapi["types/vapi.d.ts"]:::server
        end
        subgraph "Instrumentation & Config"
            direction TB
            SentryServer["sentry.server.config.ts"]:::monitoring
            SentryEdge["sentry.edge.config.ts"]:::monitoring
            InstrumentationServer["instrumentation.ts"]:::monitoring
            NextConfig["next.config.ts"]:::server
            PostCSS["postcss.config.mjs"]:::server
            TSConfig["tsconfig.json"]:::server
            PackageJSON["package.json"]:::server
            ESLint["eslint.config.mjs"]:::server
        end
    end

    %% External Services
    SupabaseDB[(PostgreSQL / Supabase)]:::database
    ClerkStripe["Clerk & Stripe (Auth & Billing)"]:::auth
    VapiCloud["Vapi Voice AI"]:::ai
    SentryCloud["Sentry Monitoring"]:::monitoring
    CDN["CDN / Public Assets"]:::cdn

    %% Relationships
    CTA -->|imports| Layout
    CompanionCard -->|imports| CompanionsListPage
    CompanionComponent -->|imports| CompanionDetailPage
    CompanionForm -->|imports| CompanionNewPage
    CompanionsList -->|imports| CompanionsListPage
    Navbar -->|renders in| Layout
    SearchInput -->|used in| CompanionsListPage
    SubjectFilter -->|used in| CompanionsListPage
    UIPrimitives -->|used by| CTA
    InstrumentationClient -->|logs to| SentryCloud

    Layout -->|renders pages| PageRoot
    Middleware -->|guards| APIRoutes
    APIRoutes -->|uses| SupabaseClient
    APIRoutes -->|calls| SentryServer
    SupabaseClient -->|connects to| SupabaseDB
    SupabaseClient -->|real-time| SupabaseDB
    VapiSDK -->|calls| VapiCloud
    CompanionActions -->|uses SDK| VapiSDK
    CompanionActions -->|uses| SupabaseClient
    APIRoutes -->|uses actions| CompanionActions
    Middleware -->|validates via| ClerkStripe
    APIRoutes -->|billing webhooks| ClerkStripe
    InstrumentationServer -->|logs to| SentryCloud

    Layout -->|serves static| CDN
    GlobalsCSS -->|styles| Layout

    %% Click Events for Components
    click CTA "https://github.com/adrianhajdin/saas-app/blob/main/components/CTA.tsx"
    click CompanionCard "https://github.com/adrianhajdin/saas-app/blob/main/components/CompanionCard.tsx"
    click CompanionComponent "https://github.com/adrianhajdin/saas-app/blob/main/components/CompanionComponent.tsx"
    click CompanionForm "https://github.com/adrianhajdin/saas-app/blob/main/components/CompanionForm.tsx"
    click CompanionsList "https://github.com/adrianhajdin/saas-app/blob/main/components/CompanionsList.tsx"
    click Navbar "https://github.com/adrianhajdin/saas-app/blob/main/components/Navbar.tsx"
    click SearchInput "https://github.com/adrianhajdin/saas-app/blob/main/components/SearchInput.tsx"
    click SubjectFilter "https://github.com/adrianhajdin/saas-app/blob/main/components/SubjectFilter.tsx"
    click UIPrimitives "https://github.com/adrianhajdin/saas-app/tree/main/components/ui/"
    click Layout "https://github.com/adrianhajdin/saas-app/blob/main/app/layout.tsx"
    click GlobalsCSS "https://github.com/adrianhajdin/saas-app/blob/main/app/globals.css"
    click PageRoot "https://github.com/adrianhajdin/saas-app/blob/main/app/page.tsx"
    click CompanionsListPage "https://github.com/adrianhajdin/saas-app/blob/main/app/companions/page.tsx"
    click CompanionDetailPage "https://github.com/adrianhajdin/saas-app/blob/main/app/companions/[id]/page.tsx"
    click CompanionNewPage "https://github.com/adrianhajdin/saas-app/blob/main/app/companions/new/page.tsx"
    click MyJourney "https://github.com/adrianhajdin/saas-app/blob/main/app/my-journey/page.tsx"
    click SubscriptionPage "https://github.com/adrianhajdin/saas-app/blob/main/app/subscription/page.tsx"
    click SignInPage "https://github.com/adrianhajdin/saas-app/blob/main/app/sign-in/[[...sign-in]]/page.tsx"
    click GlobalError "https://github.com/adrianhajdin/saas-app/blob/main/app/global-error.tsx"
    click APIRoutes "https://github.com/adrianhajdin/saas-app/blob/main/app/api/sentry-example-api/route.ts"
    click Middleware "https://github.com/adrianhajdin/saas-app/blob/main/middleware.ts"
    click SupabaseClient "https://github.com/adrianhajdin/saas-app/blob/main/lib/supabase.ts"
    click VapiSDK "https://github.com/adrianhajdin/saas-app/blob/main/lib/vapi.sdk.ts"
    click CompanionActions "https://github.com/adrianhajdin/saas-app/blob/main/lib/actions/companion.actions.ts"
    click InstrumentationServer "https://github.com/adrianhajdin/saas-app/blob/main/instrumentation.ts"
    click SentryServer "https://github.com/adrianhajdin/saas-app/blob/main/sentry.server.config.ts"
    click SentryEdge "https://github.com/adrianhajdin/saas-app/blob/main/sentry.edge.config.ts"
    click InstrumentationClient "https://github.com/adrianhajdin/saas-app/blob/main/instrumentation-client.ts"
    click Constants "https://github.com/adrianhajdin/saas-app/blob/main/constants/index.ts"
    click Soundwaves "https://github.com/adrianhajdin/saas-app/blob/main/constants/soundwaves.json"
    click TypesIndex "https://github.com/adrianhajdin/saas-app/blob/main/types/index.d.ts"
    click TypesVapi "https://github.com/adrianhajdin/saas-app/blob/main/types/vapi.d.ts"
    click NextConfig "https://github.com/adrianhajdin/saas-app/blob/main/next.config.ts"
    click PostCSS "https://github.com/adrianhajdin/saas-app/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/adrianhajdin/saas-app/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/adrianhajdin/saas-app/blob/main/package.json"
    click ESLint "https://github.com/adrianhajdin/saas-app/blob/main/eslint.config.mjs"

    %% Styles
    classDef component fill:#E0F7FA,stroke:#006064,color:#006064
    classDef server fill:#DCEDC8,stroke:#33691E,color:#33691E
    classDef service fill:#FFF9C4,stroke:#F57F17,color:#F57F17
    classDef database fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef auth fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef ai fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef monitoring fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C
    classDef cdn fill:#ECEFF1,stroke:#37474F,color:#37474F
```
