# moohamedpk/ai-saas-app architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack web application built on Next.js (App Router).
- Purpose: an AI-powered learning companion platform (“Freelance Boost AI”) where users can browse, create, and chat with AI companions, track progress, bookmark sessions, and manage their profile.

##### File structure
- Top-level directories:
- app/ – Next.js routes and pages (frontend + built-in backend API routes)
- actions/ – server-side functions for data fetching and mutations (uses Next.js server actions)
- components/ – reusable React UI components
- lib/ – shared utilities (Prisma client, helper functions)
- prisma/ – Prisma schema and PostgreSQL migration files
- public/ – static assets (images, Lottie JSON)
- app/api/webhooks/ – Next.js API route for Clerk webhooks
- Key config files: next.config.ts, tsconfig.json, prisma/schema.prisma, postcss.config.mjs
- Auth integration: Clerk via pages under app/sign-in, app/sign-up, and a webhook in app/api/webhooks/clerk/route.ts
- Styling: Tailwind CSS (globals.css)
- AI integration: Companion agent component triggers AI calls (likely via server actions in actions/companion)

##### README for additional insights
- Confirms full-stack nature: Next.js pages + server actions + Prisma + PostgreSQL
- Auth: Clerk
- UI libraries: Radix UI, Lucide React, Lottie React
- Features reinforce the need for components to handle: library browsing, session chat, bookmarks, history, progress tables

a. Main components
- Client (Browser) – Next.js React pages + components
- Next.js Server
– App Router pages (SSR/SSG)
– Server Actions in actions/…
– API Routes for webhooks (app/api/webhooks)
- Authentication Service – Clerk (OAuth flows, webhook events)
- Database – PostgreSQL accessed via Prisma client (lib/prisma.ts)
- AI Service – External AI API (e.g., OpenAI) invoked from server actions (actions/companion/*.ts)
- Static Assets CDN – files under public/
b. Relationships and interactions
1. User interacts with UI components (app/page.tsx, components/*)
2. UI triggers data fetch or mutations via:
– Next.js Server Actions (e.g., actions/companion/fetchCompanions.ts)
– Fetch to custom API routes (e.g., webhooks for Clerk)
3. Server Actions use Prisma client to read/write Postgres (companion library, bookmarks, history, lessons)
4. Server Actions call External AI Service for guided sessions (AgentComponent)
5. Clerk handles authentication flows and issues tokens; webhooks update user state via app/api/webhooks/clerk/route.ts
6. Static assets (images, JSON animations) served from public/
c. Architectural patterns and design principles
– Full-stack React (Next.js) with App Router and Server Actions
– Separation of concerns: UI components vs. data layer (actions/) vs. DB schema (prisma/)
– Modular components under components/ui, components/common, domain-specific under components/companion, components/profile, etc.
– Database migrations with Prisma Migrate
– External service integration (AI, Clerk) abstracted in lib/utils.ts or actions
d. Key technologies, frameworks, libraries
– Next.js (App Router)
– React + Tailwind CSS + Radix UI + Lottie + Lucide
– Prisma ORM + PostgreSQL
– Clerk for auth
– External AI API (e.g., OpenAI)

##### Detail
- Major folder as a component boundary: app/ vs. actions/ vs. prisma/ vs. public/
- Interactions between domain-specific modules (e.g., companionHistory action writing to CompanionHistory table)
- Don’t over-abstract: represent both API routes (webhooks) and server actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser (Client)"
        pages["Next.js App Router<br>(app/)"]:::frontend
        signin["Sign-In UI<br>(app/sign-in/[[...sign-in]]/page.tsx)"]:::frontend
        signup["Sign-Up UI<br>(app/sign-up/page.tsx)"]:::frontend
        subscription["Subscription Page<br>(app/subscription/page.tsx)"]:::frontend
        agentUI["AI Companion UI<br>(components/companion/AgentComponent.tsx)"]:::frontend
        commonUI["Common UI Components<br>(components/ui/, components/common/, etc.)"]:::frontend
        navbar["Navbar & Footer<br>(components/Navbar.tsx, components/Footer.tsx)"]:::frontend
        globalStyles["Global Styles<br>(app/globals.css)"]:::frontend
    end

    subgraph "Next.js Server"
        router["App Router<br>(app/)"]:::backend
        serverActions["Server Actions<br>(actions/)"]:::backend
        webhook["Clerk Webhook API Route<br>(app/api/webhooks/clerk/route.ts)"]:::backend
        prismaClient["Prisma Client<br>(lib/prisma.ts)"]:::backend
        utils["Shared Utilities<br>(lib/utils.ts)"]:::backend
    end

    subgraph "Database & ORM"
        prismaSchema["Prisma Schema & Migrations<br>(prisma/schema.prisma,<br/>prisma/migrations/)"]:::database
        postgres["PostgreSQL Database"]:::database
    end

    subgraph "External Services"
        clerk["Clerk Auth Service"]:::external
        aiService["External AI Service<br>(OpenAI API)"]:::external
    end

    subgraph "Static Assets"
        assets["Static Assets CDN<br>(public/)"]:::frontend
    end

    %% Interactions
    BrowserClientInteraction{{ }}:::interaction
    pages --> RouterInteraction{{ }}:::interaction
    pages -->|"navigates"| router
    signin -->|"submit auth"| router
    signup -->|"submit auth"| router
    subscription -->|"access"| router
    router -->|"serves UI"| pages
    router -->|"invoke action"| serverActions
    serverActions -->|"read/write via"| prismaClient
    prismaClient -->|"queries/mutations"| prismaSchema
    prismaSchema -->|"stores data in"| postgres
    serverActions -->|"call AI API"| aiService
    pages -->|"authenticate"| clerk
    clerk -->|"webhook event"| webhook
    webhook -->|"update user"| prismaClient
    router -->|"serve assets"| assets
    assets -->|"static files"| pages

    %% Click Events
    click pages "https://github.com/moohamedpk/ai-saas-app/tree/main/app/"
    click signin "https://github.com/moohamedpk/ai-saas-app/blob/main/app/sign-in/[[...sign-in]]/page.tsx"
    click signup "https://github.com/moohamedpk/ai-saas-app/blob/main/app/sign-up/page.tsx"
    click subscription "https://github.com/moohamedpk/ai-saas-app/blob/main/app/subscription/page.tsx"
    click globalStyles "https://github.com/moohamedpk/ai-saas-app/blob/main/app/globals.css"
    click router "https://github.com/moohamedpk/ai-saas-app/tree/main/app/"
    click serverActions "https://github.com/moohamedpk/ai-saas-app/tree/main/actions/"
    click webhook "https://github.com/moohamedpk/ai-saas-app/blob/main/app/api/webhooks/clerk/route.ts"
    click prismaClient "https://github.com/moohamedpk/ai-saas-app/blob/main/lib/prisma.ts"
    click prismaSchema "https://github.com/moohamedpk/ai-saas-app/blob/main/prisma/schema.prisma"
    click utils "https://github.com/moohamedpk/ai-saas-app/blob/main/lib/utils.ts"
    click agentUI "https://github.com/moohamedpk/ai-saas-app/blob/main/components/companion/AgentComponent.tsx"
    click commonUI "https://github.com/moohamedpk/ai-saas-app/tree/main/components/ui/"
    click assets "https://github.com/moohamedpk/ai-saas-app/tree/main/public/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#28A745,color:#28A745,stroke-width:1px
    classDef database fill:#F0F0F0,stroke:#6A737D,color:#24292e,stroke-width:1px
    classDef external fill:#FFF5D1,stroke:#D19A66,color:#D19A66,stroke-width:1px
    classDef interaction stroke-dasharray: 5 5,stroke:#888,color:#000,fill:none,stroke-width:0px
```
