How adrianhajdin/saas-app works
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.