Project Structure

Note: This is mock/placeholder content for demonstration purposes.

Learn how the codebase is organized and where to find things.

Monorepo Overview

This project uses Turborepo to manage a monorepo with multiple apps and packages.

project-root/
├── apps/                    # Applications
│   ├── web/                # Main Next.js app
│   ├── e2e/                # Playwright E2E tests
│   └── dev-tool/           # Development utilities
├── packages/               # Shared packages
│   ├── features/          # Feature packages
│   ├── ui/                # UI components
│   ├── database/          # Database utilities
│   └── billing/           # Billing integrations
├── tooling/               # Development tools
├── packages/database/      # Database schema & migrations
└── docs/                  # Documentation

Main Application (apps/web)

The primary Next.js application:

apps/web/
├── app/                    # Next.js App Router
│   ├── (marketing)/       # Public pages
│   ├── (auth)/            # Authentication
│   ├── home/              # Main application
│   │   ├── (user)/        # Personal account
│   │   └── [account]/     # Team accounts
│   ├── admin/             # Admin panel
│   └── api/               # API routes
├── components/            # Shared components
├── config/                # Configuration files
├── lib/                   # Utility functions
└── public/                # Static assets

Route Structure

Marketing Routes ((marketing))

Public-facing pages:

app/(marketing)/
├── page.tsx               # Landing page
├── pricing/               # Pricing page
├── blog/                  # Blog
└── docs/                  # Documentation

Auth Routes ((auth))

Authentication pages:

app/(auth)/
├── sign-in/
├── sign-up/
├── password-reset/
└── verify/

Application Routes (home)

Main application:

app/home/
├── (user)/                # Personal account context
│   ├── page.tsx          # Personal dashboard
│   ├── settings/         # User settings
│   └── projects/         # Personal projects
└── [account]/            # Team account context
    ├── page.tsx          # Team dashboard
    ├── settings/         # Team settings
    ├── projects/         # Team projects
    └── members/          # Team members

Packages Structure

Feature Packages (packages/features/)

Modular features:

packages/features/
├── accounts/              # Account management
├── auth/                  # Authentication
├── team-accounts/         # Team features
├── billing/               # Billing & subscriptions
├── admin/                 # Admin features
└── notifications/         # Notification system

UI Package (packages/ui/)

Shared UI components:

packages/ui/
└── src/
    ├── components/        # Shadcn UI components
    │   ├── button.tsx
    │   ├── input.tsx
    │   ├── dialog.tsx
    │   └── ...
    └── utils/             # UI utilities

Database Package (packages/database/)

Database utilities:

packages/database/
├── schema/                # Database schemas
│   ├── accounts.schema.ts
│   ├── auth.schema.ts
│   └── ...
├── src/
│   ├── client/           # Database client
│   └── migrations/       # SQL migrations

Configuration Files

Root Level

project-root/
├── package.json           # Root package.json
├── turbo.json             # Turborepo config
├── pnpm-workspace.yaml    # PNPM workspace
└── tsconfig.json          # Base TypeScript config

Application Level

apps/web/
├── next.config.js         # Next.js configuration
├── tailwind.config.ts     # Tailwind CSS
├── tsconfig.json          # TypeScript config
└── .env.local             # Environment variables

Feature Configuration

apps/web/config/
├── billing.config.ts      # Billing settings
├── feature-flags.config.ts # Feature flags
├── personal-account-navigation.config.tsx
└── team-account-navigation.config.tsx

Naming Conventions

Files

• Pages: page.tsx (Next.js convention)
• Layouts: layout.tsx
• Components: kebab-case.tsx
• Utilities: kebab-case.ts
• Types: types.ts or component-name.types.ts

Directories

• Route segments: [param] for dynamic
• Route groups: (group) for organization
• Private folders: _components, _lib
• Parallel routes: @folder

Code Organization

feature/
├── page.tsx               # Route page
├── layout.tsx             # Route layout
├── loading.tsx            # Loading state
├── error.tsx              # Error boundary
├── _components/           # Private components
│   ├── feature-list.tsx
│   └── feature-form.tsx
└── _lib/                  # Private utilities
    ├── server/            # Server-side code
    │   ├── loaders.ts
    │   └── actions.ts
    └── schemas/           # Validation schemas
        └── feature.schema.ts

Import Paths

Use TypeScript path aliases:

// Absolute imports from packages
import { Button } from '@kit/ui/button';
import { db } from '@kit/database/client';

// Relative imports within app
import { FeatureList } from './_components/feature-list';
import { loadData } from './_lib/server/loaders';

Best Practices

1. Keep route-specific code private - Use _components and _lib
2. Share reusable code - Extract to packages
3. Collocate related files - Keep files near where they're used
4. Use consistent naming - Follow established patterns
5. Organize by feature - Not by file type

Finding Your Way