Codebase Structure

Overview

Understand the file structure and directory organization to maintain consistency when adding new features, components, or functionality.

Directory Structure

create-reodor-app/
├── app/                    # Next.js App Router - Pages and routes
├── components/             # React components
├── docs/                   # Project documentation
├── hooks/                  # Custom React hooks
├── lib/                    # External service configurations and utilities
├── providers/              # React context providers
├── public/                 # Static assets (images, logos, manifests)
├── schemas/                # Generated Zod schemas (auto-generated)
├── scripts/                # Utility scripts (deployment, setup)
├── seed/                   # Database seeding configuration
├── server/                 # Server actions for data mutations
├── stores/                 # Zustand state management stores
├── supabase/               # Supabase configuration and database
├── transactional/          # React Email templates
├── types/                  # TypeScript type definitions
└── middleware.ts           # Next.js middleware (auth, route protection)

Where to Place New Code

Pages & Routes (

app/

)

Structure: Next.js App Router with file-based routing

Place here:

• Page components (

  page.tsx

  )
• Layouts (

  layout.tsx

  )
• Error boundaries (

  error.tsx

  ,

  global-error.tsx

  )
• Not found pages (

  not-found.tsx

  )
• API routes (

  api/*/route.ts

  )
• Route-specific loading states (

  loading.tsx

  )
• SEO metadata (

  robots.ts

  ,

  sitemap.ts

  ,

  opengraph-image.png

  )
• Favicons and app icons

Examples:

• app/oppgaver/page.tsx

  - Todos feature page

• app/auth/sign-in/page.tsx

  - Sign in page

• app/api/cron/*/route.ts

  - Cron job endpoints

• app/layout.tsx

  - Root layout with providers

Components (

components/

)

Structure: Feature-based organization + shared components

Place here:

• Feature directories (

  components/[feature]/

  ) - Feature-specific components
  • Example:

    components/todos/

    ,

    components/auth/

    ,

    components/admin/

• Shared components - Components used across features
  • Example:

    navbar.tsx

    ,

    footer.tsx

    ,

    error-boundary.tsx

• UI library (

  components/ui/

  ) - shadcn/ui components
• Specialized UI (

  components/kibo-ui/

  ) - Kibo UI components
• Magic UI (

  components/magicui/

  ) - Magic UI components

Naming: Use kebab-case for directories, PascalCase for component files

Examples:

• components/todos/todo-form.tsx

  - Todo form component

• components/todos/todo-dialog.tsx

  - Todo dialog wrapper

• components/auth/auth-form.tsx

  - Authentication form

• components/ui/button.tsx

  - shadcn/ui button component

Server Actions (

server/

)

Purpose: Type-safe server-side data operations with authentication

Place here:

• Database CRUD operations
• Authenticated data mutations
• Server-side business logic

Naming:

[feature].actions.ts

Examples:

• server/todo.actions.ts

  - Todo CRUD operations

• server/profile.actions.ts

  - Profile management

• server/admin.actions.ts

  - Admin operations

Pattern: Individual exported async functions, not default exports

Custom Hooks (

hooks/

)

Purpose: Reusable React hooks for client-side logic

Place here:

• Data fetching hooks (TanStack Query)
• File upload hooks
• Authentication hooks
• Form state management hooks
• UI state hooks (media queries, scroll position, etc.)

Naming:

use-[hook-name].ts

Examples:

• hooks/use-auth.ts

  - Authentication state

• hooks/use-upload-todo-attachments.ts

  - File upload logic

• hooks/use-media-query.ts

  - Responsive breakpoint detection

State Management (

stores/

)

Purpose: Global state with Zustand

Place here:

• Application-wide state
• Persisted state (localStorage, sessionStorage)
• Shared UI state

Naming:

[feature]-store.ts

use-[feature]-store.ts

Examples:

• stores/setup-steps-store.ts

  - Setup wizard state

Database (

supabase/

)

Structure:

supabase/
├── schemas/        # Declarative SQL schemas (source of truth)
├── migrations/     # Generated SQL migrations (auto-generated)
└── functions/      # Edge functions (Deno runtime)

Place here:

• schemas/ - Declarative database schemas, RLS policies, triggers

  • 01-schema.sql

    - Tables, enums, indexes

  • 02-policies.sql

    - Row Level Security policies

  • 03-triggers.sql

    - Database triggers
• migrations/ - Generated from schemas (DO NOT edit manually)
• functions/ - Supabase Edge Functions for serverless operations

Workflow:

1. Edit schema in

   schemas/

2. Run

   bun db:diff <name>

   to generate migration
3. Review generated migration in

   migrations/

4. Run

   bun migrate:up

   to apply

Type Definitions (

types/

)

Purpose: TypeScript types and interfaces

Place here:

• database.types.ts - Generated from Supabase (auto-generated, DO NOT edit)
• index.ts - Custom types, shared filter types, runtime-agnostic types
• Feature-specific type definitions

Examples:

• types/database.types.ts

  - Auto-generated Supabase types

• types/index.ts

  - Custom types like

  BookingFilters

  ,

  ServiceFilters

Schemas (

schemas/

)

Purpose: Auto-generated Zod validation schemas

Content:

• database.schema.ts

  - Generated from Supabase types (DO NOT edit manually)

Usage: Import schemas for validation in server actions and forms

Generation: Run

bun gen:types

External Services (

lib/

)

Purpose: Service configurations and utilities

Place here:

• Service clients (

  resend.ts

  ,

  lib/supabase/client.ts

  )
• Service utilities (

  resend-utils.ts

  ,

  lib/supabase/storage.ts

  )
• Configuration (

  brand.ts

  ,

  navigation.ts

  ,

  permissions.ts

  )
• Helper functions (

  utils.ts

  - cn(), formatting, etc.)

Structure:

lib/
├── supabase/           # Supabase configuration
│   ├── client.ts       # Browser client
│   ├── server.ts       # Server client
│   └── storage.ts      # Storage utilities
├── brand.ts            # Brand configuration
├── navigation.ts       # Navigation structure
├── utils.ts            # Shared utilities
└── [service].ts        # External service configs

React Providers (

providers/

)

Purpose: React Context providers for app-wide state

Place here:

• TanStack Query provider
• Theme providers
• Authentication providers
• Any context providers

Examples:

• providers/tanstack-query-provider.tsx

Email Templates (

transactional/emails

)

Purpose: React Email templates for transactional emails

Place here:

• Email components built with React Email
• Email-specific utilities

Examples:

• transactional/emails/welcome.tsx

• transactional/emails/password-reset.tsx

Documentation (

docs/

)

Structure:

docs/
├── business/       # Business features and workflows
└── technical/      # Technical implementation details

Place here:

• business/ - Feature docs, user workflows, business logic
• technical/ - Architecture, API docs, deployment guides

Examples:

• docs/technical/google-auth-setup.md

• docs/technical/railway-deployment.md

Static Assets (

public/

)

Purpose: Static files served at root path

Place here:

• Logos and brand assets
• Web app manifest images
• Static images referenced by absolute paths
• Files that need specific public URLs

Structure:

public/
├── logos/                          # Logo variations
├── web-app-manifest-192x192.png   # PWA icons
└── web-app-manifest-512x512.png

Note: Favicons and app icons go in

app/

public/

Utility Scripts (

scripts/

)

Purpose: Development and deployment automation

Place here:

• Deployment scripts
• Setup scripts
• Database utilities
• Build automation

Examples:

• scripts/railway-setup.sh

• scripts/ensure-transactional-deps-installed.sh

Database Seeding (

seed/

)

Purpose: Snaplet configuration for database seeding

Place here:

• Snaplet configuration
• Seed data scripts

Root-Level Files

• middleware.ts - Next.js middleware for auth and route protection
• next.config.ts - Next.js configuration
• tailwind.config.ts - Tailwind CSS configuration
• seed.config.ts - Database seeding configuration
• next-env.d.ts - Next.js TypeScript declarations (auto-generated)

Key Principles

1. Feature-based organization - Group related files by feature (e.g.,

   components/todos/

   ,

   server/todo.actions.ts

   )
2. Separation of concerns - Keep server logic (

   server/

   ) separate from client components (

   components/

   )
3. Generated files - Never edit auto-generated files (

   types/database.types.ts

   ,

   schemas/database.schema.ts

   ,

   migrations/

   )
4. Naming conventions - Use kebab-case for files, PascalCase for components, camelCase for functions

Common Workflows

Adding a New Feature

1. Database: Update

   supabase/schemas/01-schema.sql

   with new database schema state. Refer to

   skills/database-schema-extension/SKILL.md

   for guidance.
2. Server Actions: Create

   server/[feature].actions.ts

3. Components: Create

   components/[feature]/

   directory
4. Hooks: Add custom hooks to

   hooks/use-[feature].ts

   if needed.
5. Page: Create

   app/[path-to-feature]/page.tsx

   . It can be nested as needed.
6. Types: Custom types go in

   types/index.ts

Adding a New UI Component

1. Shared component:

   components/[name].tsx

2. Feature component:

   components/[feature]/[name].tsx

3. shadcn/ui: Run

   bunx --bun shadcn@latest add [component]

   (auto-adds to

   components/ui/

   )

Adding Authentication

1. Server action: Add to

   server/auth.actions.ts

2. Middleware: Update route protection in

   middleware.ts

3. Components: Add to

   components/auth/

4. Hooks: Update

   hooks/use-auth.ts

Quick Reference

app/[route]/page.tsx

app/oppgaver/page.tsx

server/[feature].actions.ts

server/todo.actions.ts

components/[feature]/[name].tsx

components/todos/todo-form.tsx

hooks/use-[name].ts

hooks/use-auth.ts

stores/[name]-store.ts

stores/setup-steps-store.ts

supabase/schemas/01-schema.sql

transactional/[name]-email.tsx

transactional/welcome-email.tsx

lib/utils.ts

lib/[service]-utils.ts

lib/resend-utils.ts

types/index.ts

app/api/[route]/route.ts

app/api/cron/demo/route.ts