---
title: "Project Structure"
description: "Understanding the monorepo structure and organization."
publishedAt: 2024-04-11
order: 3
status: "published"
---

> **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
│   ├── supabase/          # Supabase utilities
│   └── billing/           # Billing integrations
├── tooling/               # Development tools
├── supabase/              # 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
└── supabase/              # Supabase setup
```

## 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
```

### Supabase Package (`packages/supabase/`)

Database utilities:

```
packages/supabase/
├── schema/                # Declarative schemas
│   ├── accounts.schema.ts
│   ├── auth.schema.ts
│   └── ...
├── src/
│   ├── clients/          # Supabase clients
│   ├── hooks/            # React hooks
│   └── middleware/       # Auth middleware
└── 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/
├── paths.config.ts        # Route paths
├── 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:

```typescript
// Absolute imports from packages
import { Button } from '@kit/ui/button';
import { createClient } from '@kit/supabase/server-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

| Looking for... | Location |
|----------------|----------|
| UI Components | `packages/ui/src/components/` |
| Database Schema | `packages/supabase/schema/` |
| API Routes | `apps/web/app/api/` |
| Auth Logic | `packages/features/auth/` |
| Billing Code | `packages/features/billing/` |
| Team Features | `packages/features/team-accounts/` |
| Config Files | `apps/web/config/` |
| Types | `*.types.ts` files throughout |