project-structure

name	project-structure
description	Project structure and file organization guidelines

Project Structure

Main Structure

• We use Turborepo with pnpm workspaces
• Main app is in apps/web
• Packages are in the packages folder
• Server actions are in apps/web/utils/actions folder

.
├── apps
│   ├── web/             # Main Next.js application
│   │   ├── app/         # Next.js App Router
│   │   │   ├── (app)/   # Main application pages
│   │   │   │   ├── assistant/     # AI assistant feature
│   │   │   │   ├── reply-zero/     # Reply Zero feature
│   │   │   │   ├── settings/       # User settings
│   │   │   │   ├── setup/          # Main onboarding
│   │   │   │   ├── clean/          # Bulk email cleanup
│   │   │   │   ├── smart-categories/ # Smart sender categorization
│   │   │   │   ├── bulk-unsubscribe/ # Bulk unsubscribe
│   │   │   │   ├── stats/          # Email analytics
│   │   │   │   ├── mail/           # Email client (in beta)
│   │   │   │   └── ... (other app routes)
│   │   │   ├── api/    # API Routes
│   │   │   │   ├── knowledge/      # Knowledge base API
│   │   │   │   ├── reply-tracker/  # Reply tracking
│   │   │   │   ├── clean/          # Cleanup API
│   │   │   │   ├── ai/            # AI features API
│   │   │   │   ├── user/          # User management
│   │   │   │   ├── google/        # Google integration
│   │   │   │   ├── auth/          # Authentication
│   │   │   │   └── ... (other APIs)
│   │   │   ├── (landing)/  # Marketing/landing pages
│   │   │   ├── blog/       # Blog pages
│   │   │   ├── layout.tsx  # Root layout
│   │   │   └── ... (other app files)
│   │   ├── utils/       # Utility functions and helpers
│   │   │   ├── actions/    # Server actions
│   │   │   ├── ai/         # AI-related utilities
│   │   │   ├── llms/       # Language model utilities
│   │   │   ├── gmail/      # Gmail integration utilities
│   │   │   ├── redis/      # Redis utilities
│   │   │   ├── user/       # User-related utilities
│   │   │   ├── parse/      # Parsing utilities
│   │   │   ├── queue/      # Queue management
│   │   │   ├── error-messages/  # Error handling
│   │   │   └── *.ts        # Other utility files (auth, email, etc.)
│   │   ├── public/      # Static assets (images, fonts)
│   │   ├── prisma/      # Prisma schema and client
│   │   ├── styles/      # Global CSS styles
│   │   ├── providers/   # React Context providers
│   │   ├── hooks/       # Custom React hooks
│   │   ├── sanity/      # Sanity CMS integration
│   │   ├── __tests__/   # AI test files (Vitest)
│   │   ├── scripts/     # Utility scripts
│   │   ├── store/       # State management
│   │   ├── types/       # TypeScript type definitions
│   │   ├── next.config.mjs
│   │   ├── package.json
│   │   └── ... (config files)
├── packages
    ├── tinybird/
    ├── loops/
    ├── resend/
    ├── tinybird-ai-analytics/
    └── tsconfig/

File Naming and Organization

• Use kebab case for route directories (e.g., api/hello-world/route)
• Use PascalCase for components (e.g. components/Button.tsx)
• Shadcn components are in components/ui
• All other components are in components/
• Colocate files in the folder where they're used unless they can be used across the app
• If a component can be used in many places, place it in the components folder

New Pages

• Create new pages at: apps/web/app/(app)/PAGE_NAME/page.tsx
• Components for the page are either in page.tsx or in the apps/web/app/(app)/PAGE_NAME folder
• Pages are Server components for direct data loading
• Use swr for data fetching in deeply nested components
• Components with onClick must be client components with use client directive
• Server action files must start with use server

Utility Functions

• Create utility functions in utils/ folder for reusable logic
• Use lodash utilities for common operations (arrays, objects, strings)
• Import specific lodash functions to minimize bundle size:

  import groupBy from "lodash/groupBy";