Project Structure

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:

// 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