File Structure

We are using a Turbo Monorepo setup with the following file structure. Key organizational principles:

Clear separation between public and private routes
Server Actions organized on top level
Feature-based organization for complex functionality, categorized into shared and domain-specific modules
Global modules for truly cross-cutting concerns (components, hooks, utils, etc.)

📁 Overview

├── 📁 public/              # Static files served at root path
│   ├── 📁 videos/          # Public videos
│   └── 🌐 favicon.ico      # Browser favicon
│   |
|   ├── 📁 messages/            # i18n message files
|   │   ├── 🌍 en.json          # English translations
|   │   ├── 🌍 de.json          # German translations
|   │   └── ...                 # Other language files
│   |
└── 📁 src/                 # Source code
    ├── 📘 instrumentation.ts  # Server instrumentation code
    ├── 📘 middleware.ts       # Next.js middleware for request handling
    │
    ├── 📁 app/                # Next.js App Router directory
    │   ├── 🎨 globals.css       # Root global styles
    │   ├── ⚛️ global-error.tsx  # App-level error handling
    │   ├── 📘 robots.ts         # SEO robots configuration
    │   │
    │   ├── 📁 api/              # API routes
    │   │   └── ...
    │   │
    │   └── 📁 [lang]/           # Dynamic language routing
    │       ├── ⚛️ error.tsx       # Language-specific error handling
    │       ├── ⚛️ layout.tsx      # Language-specific layout
    │       ├── ⚛️ loading.tsx     # Language-specific loading
    │       ├── ⚛️ not-found.tsx   # Language-specific 404
    │       │
    │       ├── 📁 (public)/       # Public routes
    │       │   ├── 📁 (auth)/     # Authentication routes
    │       │   │    ├── 📁 login/        # Login pages
    │       │   │    │   └── ⚛️ page.tsx  # Login page component
    │       │   │    ├── ...              # Other auth pages
    │       │   │
    │       │   ├── ⚛️ page.tsx    # Landing page
    │       │   └── 📁 ...         # Other public pages
    │       │
    │       └── 📁 (private)/      # Private routes (require auth)
    │           ├── 📁 [courseId]/    # Dynamic course routes
    │           │   └── ⚛️ page.tsx   # Course page component
    │           └── ...               # Other private routes
    │
    ├── 📁 actions/              # Server Actions
    │   ├── 📁 db-tables/        # Database table operations
    │   │   └── ⚛️ users.ts           # User table operations
    │   ├── 📁 db-functions/     # Database function calls
    │   │   └── ⚛️ get-chunks.ts      # Chunk matching function
    │   └── 📘 ...               # Other global server actions
    │
    ├── 📁 features/             # Feature Modules
    │   ├── 📁 shared/           # Shared features (usable across domains)
    │   │   └── 📁 TopicSelector/ # Example shared feature
    │   │       ├── 📝 README.md
    │   │       ├── 📁 components/
    │   │       ├── 📁 hooks/
    │   │       ├── ...          # Standard feature structure
    │   │       └── ⚛️ index.tsx  # Feature entry point
    │   │
    │   └── 📁 domain/           # Domain-specific features
    │       └── 📁 course/      # Example domain feature (e.g., specific to 'course' domain)
    │           ├── 📝 README.md
    │           ├── 📁 components/
    │           ├── 📁 hooks/
    │           ├── ...          # Standard feature structure
    │           └── ⚛️ index.tsx  # Feature entry point
    │
    ├── 📁 components/          # Global, shared components (UI primitives, layouts)
    │   └── 📁 Buttons/          # Custom button components
    │       ├── ⚛️ index.tsx          # Buttons entry point
    │       └── ⚛️ LoadingButton.tsx  # Loading button variant
    │
    ├── 📁 providers/           # Global providers
    │   ├── 📘 index.ts               # Providers entry point
    │   └── ⚛️ userProvider.tsx       # User context provider
    │
    ├── 📁 hooks/               # Global, shared hooks
    │   ├── 📘 index.ts            # Hooks entry point
    │   └── 📘 useExampleHook.ts   # Example custom hook
    │
    ├── 📁 constants/           # Global constants
    │   ├── 📘 index.ts           # Constants entry point
    │   ├── 📁 config/            # Configuration constants
    │   │   ├── 📘 usage-limits.ts    # Usage limit constants
    │   └── 📘 routes.ts          # Route constants
    │
    ├── 📁 types/               # Global TypeScript types
    │   ├── 📘 index.ts           # Types entry point
    │   ├── 📁 api/               # API-related types
    │   └── 📁 db/                # Data model types (exports from supabase)
    │       ├── 📘 tables.ts         # Database table types
    │       └── 📘 enums.ts          # Database enum types
    │
    ├── 📁 utils/               # Global, shared utilities
    │   ├── 📁 api/               # API utilities
    │   │   └── 📘 index.ts         # API utils entry
    │   └── 📘 index.ts           # Utils entry point
    │
    ├── 📁 i18n/                # Internationalization utilities
    │   ├── 📘 request.ts         # i18n request helpers
    │   └── 📘 routing.ts         # i18n routing helpers
    │
    └── 📁 styles/              # Global styles

📂 web/ - Root Directory

The root directory contains three main sections:

public/: Static files served directly at the root path
- videos/: Public video assets
- favicon.ico: Browser favicon
messages/: Internationalization JSON files
- en.json: English translations
- de.json: German translations
src/: Main source code directory
- Contains all application code, including the Next.js app directory

🚀 app/ - Next.js App Router

The src/app/ directory follows Next.js 14 App Router conventions with:

Root level files:
- global-error.tsx: App-level error handling
- robots.ts: SEO configuration
api/: API route handlers
- Organized by feature/functionality
- RESTful endpoint structure
[lang]/: Dynamic language routing
- Core files:
  - error.tsx: Language-specific error handling
  - layout.tsx: Language-specific layout
  - loading.tsx: Language-specific loading
  - not-found.tsx: Language-specific 404
- Route groups:
  - (public)/: Public routes
    - (auth)/: Authentication routes
      - login/: Login pages
      - Other auth-related pages
    - page.tsx: Landing page
    - Other public pages
  - (private)/: Protected routes
    - [courseId]/: Dynamic course routes
    - Other protected content

Note: middleware.ts and instrumentation.ts are located in the src/ root directory, not in the app directory.

⚡ actions/ - Server Actions

Server Actions (src/actions/) are organized in:

db-tables/: Database table operations
- users.ts: User table operations
- Other table-specific operations
db-functions/: Database function calls
- get-chunks.ts: Chunk matching function
- Other database utilities

🧩 features/ - Feature Modules

Features (src/features/) represent distinct areas of application functionality. They are organized into two main categories:

features/shared/: Contains features designed to be reusable across different business domains. These often encapsulate common UI patterns or workflows.
- Example: TopicSelector/ could be used in course creation, user profiles, content filtering, etc.
features/domain/: Contains features specific to a particular business domain (e.g., courses, billing, admin). These are typically not reused outside their domain.
- Example: course/ might contain all functionality related only to viewing and interacting with a course.

Each feature follows a standard internal structure:

README.md: Feature documentation
components/: Feature-specific React components
sub-features/: Smaller, nested feature modules (optional)
hooks/: Feature-specific React hooks
utils/: Feature-specific utility functions
providers/: Feature-specific context providers (if needed)
types/: Feature-specific TypeScript types
server/: Server-side logic related to the feature
- actions.ts: Server actions specific to the feature
- utils.ts: Server-side utility functions for the feature
index.tsx: The main entry point exporting the feature's public API (often a component or set of hooks/functions).

Example structure for a feature (e.g., features/shared/TopicSelector/ or features/domain/course/):

📁 features/
└── 📁 [shared|domain]/
    └── 📁 FeatureName/
        ├── 📝 README.md
        ├── 📁 components/
        │   └── ⚛️ SpecificComponent.tsx
        ├── 📁 hooks/
        │   └── 📘 useFeatureHook.ts
        ├── 📁 utils/
        ├── 📁 types/
        ├── 📁 server/
        │   ├── ⚛️ actions.ts
        │   └── ⚛️ utils.ts
        └── ⚛️ index.tsx      # Feature entry point

🧱 components/ - Global Components

Global components (src/components/) are general-purpose UI elements used across multiple features or layouts. These are typically stateless or rely on global context/props.

Example: Buttons/, Modals/, Layouts/
Buttons/: Custom button components
- index.tsx: Entry point
- LoadingButton.tsx: Loading variant

🌍 src/ - Global Resources

The src/ directory contains:

Root level files:
- middleware.ts: Request handling middleware
- instrumentation.ts: Server instrumentation
providers/: Context providers
- index.ts: Entry point
- userProvider.tsx: User context
hooks/: Global hooks
- index.ts: Entry point
- useExampleHook.ts: Example hook
constants/: Global constants
- index.ts: Entry point
- config/: Configuration
  - usage-limits.ts: Usage limits
- routes.ts: Route definitions
types/: Global types
- index.ts: Entry point
- api/: API types
- db/: Database types
  - tables.ts: Database table types
  - enums.ts: Database enum types
utils/: Global utilities
- api/: API utilities
  - index.ts: API utils
- index.ts: General utils
i18n/: Internationalization utilities
- request.ts: Request helpers
- routing.ts: Routing helpers
styles/: Global styles
- Theme configurations
- Design tokens
- Style utilities

✨ web/ - Best Practices

Keep features isolated and self-contained within features/shared/ or features/domain/
Use consistent naming conventions
Maintain clear separation between global resources (components/, hooks/, utils/ etc.) and feature-specific code
Include appropriate documentation (especially README.md for features)
Co-locate related code within features (components, tests, styles, server logic)
Follow Next.js conventions for special files
Keep translations organized and separated
Keep constants and types close to where they're used
Implement proper styling organization

📁 Overview​

📂 web/ - Root Directory​

🚀 app/ - Next.js App Router​

⚡ actions/ - Server Actions​

🧩 features/ - Feature Modules​

🧱 components/ - Global Components​

🌍 src/ - Global Resources​

✨ web/ - Best Practices​