tiktok-shop

Imported from Abbasa5251/tiktok-shop (AGENTS.md). Install upstream with npx skills add Abbasa5251/tiktok-shop. Copyright stays with the author.

Project Overview

This is a TikTok Shop analytics app where users can connect their tiktok shop using app_key and app_secret and we will be storing the data in DB so that we can show some insights to the users for their shops.

Built with Next.js 15 (App Router), using Better Auth for authentication, Prisma for database management, and PostgreSQL as the database. The project uses shadcn/ui components with Tailwind CSS v4 for styling.

Key Commands

Development

• npm run dev - Start development server with Turbopack
• npm run build - Build production bundle with Turbopack
• npm start - Start production server
• npm run lint - Run ESLint

Database (Prisma)

• npx prisma generate - Generate Prisma Client after schema changes
• npx prisma migrate dev - Create and apply migrations in development
• npx prisma migrate deploy - Apply migrations in production
• npx prisma studio - Open Prisma Studio to view/edit database
• npx prisma db push - Push schema changes without creating migrations (dev only)

UI Components (shadcn/ui)

• npx shadcn@latest add <component> - Add new shadcn/ui component
• Components are installed to src/components/ui/ with "new-york" style

Architecture

Authentication System

The project uses Better Auth with the following setup:

1. Server-side auth (src/lib/auth.ts):

   • Uses Prisma adapter connected to PostgreSQL
   • Email/password authentication enabled
   • Organization plugin configured with custom fields: accessKey and secretKey
   • Auth API routes exposed at /api/auth/* via catch-all route

2. Client-side auth (src/lib/auth-client.ts):

   • Better Auth client with organization plugin
   • Type-safe organization fields inferred from server auth config

3. Auth routes:

   • Sign-in page: src/app/(auth)/sign-in/page.tsx
   • Sign-up page: src/app/(auth)/sign-up/page.tsx
   • Auth API handler: src/app/api/auth/[...all]/route.ts

Database Schema

Prisma schema (prisma/schema.prisma) includes:

• User: Core user model with email/password authentication
• Session: User sessions with IP and user agent tracking
• Account: OAuth and credential accounts (Better Auth integration)
• Verification: Email verification tokens

The Prisma client is instantiated in src/lib/prisma.ts with singleton pattern to prevent multiple instances in development.

Project Structure

• src/app/ - Next.js App Router pages and API routes
  • (auth)/ - Authentication pages (route group, doesn't affect URL)
  • api/auth/[...all]/ - Better Auth catch-all API handler
  • dashboard/ - Main dashboard page
• src/components/ - React components
  • ui/ - shadcn/ui components
• src/lib/ - Shared utilities and configurations
  • auth.ts - Server-side Better Auth configuration
  • auth-client.ts - Client-side Better Auth instance
  • prisma.ts - Prisma Client singleton
  • utils.ts - Utility functions (cn helper for Tailwind)
• prisma/ - Prisma schema and migrations

Configuration

• Path aliases: @/* maps to src/* (configured in tsconfig.json)
• Styling: Tailwind CSS v4 with shadcn/ui components using "new-york" style and neutral base color
• TypeScript: Strict mode enabled with ES2017 target
• Build tool: Turbopack enabled for faster builds

Environment Setup

Required environment variables (.env):

• DATABASE_URL - PostgreSQL connection string
• Better Auth will need additional variables for production (check Better Auth docs)

Development Workflow

When making database changes:

1. Update prisma/schema.prisma
2. Run npx prisma migrate dev to create and apply migration
3. Prisma Client is auto-generated during migration

When adding Better Auth organization features:

• Server config changes go in src/lib/auth.ts
• Client config must sync with server using inferOrgAdditionalFields<typeof auth>()
• Organization models require additional schema fields in the plugin configuration

When working with forms:

• Use react-hook-form with zod validation
• Form components from shadcn/ui are available in src/components/ui/form.tsx