How moohamedpk/ai-saas-app works
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