# Navigating the Tanstack Start Supabase SaaS Kit Codebase

> Understand the Turborepo monorepo structure, key directories, and where to add your custom code.

*Canonical: https://makerkit.dev/docs/tanstack-supabase/installation/navigating-codebase*

---

The kit uses Turborepo to organize code into reusable packages. Understanding this structure helps you know where to find things and where to add your own code.

## Top-Level Structure

```
├── apps/
│   ├── web/          # Main Tanstack Start application
│   └── e2e/          # Playwright end-to-end tests
├── packages/
│   ├── features/     # Feature modules (auth, accounts, admin)
│   ├── ui/           # Shared UI components
│   ├── supabase/     # Database client and types
│   ├── billing/      # Payment integrations
│   ├── mailers/      # Email providers
│   └── ...           # Other shared packages
└── turbo.json        # Turborepo configuration
```

## Where You'll Work Most

**90% of your work** happens in `apps/web/`. The packages provide infrastructure; you build your product in the app.

### apps/web/ Directory

```
apps/web/
├── src/
│   ├── routes/       # File-based routes (TanStack Router)
│   ├── components/   # App-specific components
│   ├── config/       # Application configuration
│   ├── lib/          # App-specific utilities
│   └── styles/       # Global CSS
├── content/          # CMS content (Keystatic)
└── supabase/         # Migrations and database tests
```

| Directory | What Goes Here |
|-----------|---------------|
| `src/routes/` | All routes and pages |
| `src/components/` | Components specific to this app |
| `src/config/` | App settings, feature flags, navigation |
| `src/lib/` | Utilities that don't belong in packages |
| `supabase/` | Database migrations and seed data |

## Routing Structure

Routes use [TanStack Router file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing) under `src/routes/`. The route tree is generated into `src/routeTree.gen.ts` (run `pnpm --filter web generate-routes`) — never edit that file by hand.

```
src/routes/
├── __root.tsx            # Root layout (wraps every route)
├── _marketing/           # Public pages — pathless layout (landing, pricing, blog)
├── auth/                 # Authentication pages
├── home/                 # Authenticated dashboard
│   ├── _user/            # Personal account routes — pathless layout
│   └── $account/         # Team account routes — dynamic segment
├── admin/                # Super admin dashboard
├── join/                 # Team invitation acceptance
├── docs/                 # Documentation
├── api/                  # API route handlers
├── update-password.tsx   # Password reset completion
└── identities.tsx        # OAuth identity linking
```

### File Conventions Explained

A folder with an underscore prefix (e.g. `_marketing`, `_authenticated`) is a **pathless layout route**: it shares a layout across its children but does not add a URL segment. `route.tsx` defines a layout for a folder, and `index.tsx` defines its index page.

**`_marketing`** — Pathless layout for public pages. URLs don't include "_marketing":
- `src/routes/_marketing/index.tsx` → `/`
- `src/routes/_marketing/pricing.tsx` → `/pricing`

**`_authenticated`** — Pathless guard shell for the whole authenticated area. It loads the active-account workspace once and exposes it on the router context. Its sibling sections mount their own sidebars:
- `src/routes/_authenticated/dashboard/index.tsx` → `/dashboard`
- `src/routes/_authenticated/settings/index.tsx` → `/settings`
- `src/routes/_authenticated/settings/members.tsx` → `/settings/members`
- `src/routes/_authenticated/settings/billing/index.tsx` → `/settings/billing`

There is no account slug in these URLs. The active account (personal or team) is resolved from the database, so the same static paths serve every workspace — switching the active account re-runs the loaders without changing the URL.

Internationalization is handled by `use-intl` with the active locale stored in a cookie — locales are not encoded in the URL path.

## Packages Overview

Packages provide reusable functionality. Import from them; don't modify unless necessary.

### Feature Packages (`packages/features/`)

| Package | Import | Contains |
|---------|--------|----------|
| `@kit/auth` | `@kit/auth/*` | Sign in/up forms, auth hooks |
| `@kit/accounts` | `@kit/accounts/*` | Personal account components |
| `@kit/team-accounts` | `@kit/team-accounts/*` | Team management, invitations |
| `@kit/admin` | `@kit/admin/*` | Super admin dashboard |
| `@kit/notifications` | `@kit/notifications/*` | In-app notifications |

### Infrastructure Packages

| Package | Import | Contains |
|---------|--------|----------|
| `@kit/ui` | `@kit/ui/*` | Shadcn components, design system |
| `@kit/supabase` | `@kit/supabase/*` | Database clients, types |
| `@kit/billing` | `@kit/billing/*` | Subscription logic |
| `@kit/mailers` | `@kit/mailers/*` | Email sending |

## Adding Your Own Code

### New Pages

Add routes in `apps/web/src/routes/`:

```
# Public page
apps/web/src/routes/_marketing/features.tsx → /features

# Authenticated app page
apps/web/src/routes/_authenticated/dashboard/projects.tsx → /dashboard/projects

# Authenticated settings page
apps/web/src/routes/_authenticated/settings/integrations.tsx → /settings/integrations
```

After adding or renaming route files, regenerate the route tree with `pnpm --filter web generate-routes` (or let the dev server do it automatically).

### New Components

Add to `apps/web/src/components/` for app-specific components:

```
apps/web/src/components/
├── dashboard/
│   ├── stats-card.tsx
│   └── activity-feed.tsx
└── projects/
    ├── project-list.tsx
    └── project-form.tsx
```

### New Database Tables

1. Create migration in `apps/web/supabase/migrations/`
2. Run `pnpm run supabase:web:reset` to apply
3. Run `pnpm run supabase:web:typegen` to update types

## Configuration Files

Located in `apps/web/src/config/`:

| File | Purpose | When to Edit |
|------|---------|--------------|
| `app.config.ts` | App name, URLs | During initial setup |
| `auth.config.ts` | Auth providers | Adding OAuth providers |
| `billing.config.ts` | Plans, prices | Setting up billing |
| `feature-flags.config.ts` | Feature toggles | Enabling/disabling features |
| `paths.config.ts` | Route constants | Adding new routes |
| `*-navigation.config.tsx` | Sidebar menus | Customizing navigation |

## Next Steps

- [Review common commands](/docs/tanstack-supabase-turbo/installation/common-commands) for daily development
- [Configure the app](/docs/tanstack-supabase-turbo/configuration/application-configuration) for your product
- [Add marketing pages](/docs/tanstack-supabase-turbo/development/marketing-pages) to start building