SurfStack

Overview

The project follows a feature-based architecture with clear separation of concerns. Everything is organized under src/ with specific purposes for each directory.

Root Structure

src/
├── app/             # Next.js App Router (pages, layouts, API routes)
├── components/      # Shared UI components
├── config/          # App-wide configuration
├── db/              # Database schema and operations
├── emails/          # Email templates (React Email)
├── env/             # Environment variable validation
├── features/        # Feature-specific modules
├── forms/           # Form utilities and abstractions
├── hooks/           # Shared React hooks
├── i18n/            # Internationalization setup
├── layouts/         # Page layout components
├── lib/             # Utilities and library integrations
├── messages/        # Translation files
├── providers/       # React context providers
├── routes/          # Declarative routing configuration
├── store/           # Client-side state (Zustand)
├── styles/          # Global styles and Tailwind
├── trpc/            # oRPC routers and setup
└── types/           # Global type definitions

Key Directories

`src/app/`

Next.js App Router pages and API routes. Organized by route groups:

app/
├── [locale]/                  # Locale-based routing
│   ├── (site)/               # Public pages
│   │   ├── page.tsx          # Homepage
│   │   ├── layout.tsx        # Site layout
│   │   └── ...
│   ├── (dashboard)/          # Authenticated pages
│   │   ├── dashboard/
│   │   └── layout.tsx        # Dashboard layout
│   └── (admin)/              # Admin pages
│       └── layout.tsx        # Admin layout
├── api/                       # API routes
│   └── trpc/[trpc]/route.ts  # oRPC handler
└── global-error.tsx           # Global error boundary

Each route folder should contain:

page.tsx - The page component
page.info.ts - Route configuration for declarative routing
layout.tsx - Shared layout (optional)
loading.tsx - Loading UI (optional)

`src/features/`

Feature-based modules following the 5-file pattern:

features/<feature-name>/
├── schema.ts       # Zod schemas and types
├── functions.ts    # Server-side DB operations
├── hooks.ts        # Client-side oRPC hooks
├── fields.tsx      # (Optional) Form field components
├── prompts.tsx     # (Optional) Dialog wrappers
├── components/     # Feature-specific components
└── index.ts        # Barrel export

Examples:

features/auth/ - Authentication logic
features/api-keys/ - API key management
features/organizations/ - Organization management
features/settings/ - User settings

`src/db/`

Database schema, operations, and configuration:

db/
├── index.ts                  # Drizzle client export
├── drizzle-operations.ts     # CRUD abstraction
├── enums.ts                  # Database enums
├── facade.ts                 # Centralized DB access
├── rls.ts                    # Row Level Security utilities
├── table-utils.ts            # Table creation helpers
├── tags.ts                   # Cache tags for invalidation
├── migrations/               # SQL migration files
└── tables/                   # Table definitions
    ├── index.ts
    ├── auth.ts               # User, session, account
    ├── api-keys.ts           # API keys
    ├── organizations.ts      # Organizations
    └── settings.ts           # User settings

`src/rpc/`

oRPC API layer for type-safe client-server communication:

trpc/
├── procedures/
│   ├── routers/              # Feature-specific routers
│   │   ├── auth.ts
│   │   ├── organizations.ts
│   │   └── ...
│   ├── root.ts               # Root router combining all
│   └── rpc.ts               # Procedures and middleware
├── react.tsx                 # React Query integration
├── server.tsx                # Server-side caller
├── openapi.ts                # OpenAPI document generation
└── tags.ts                   # OpenAPI tags

`src/components/`

Shared UI components:

components/
├── ui/                       # Shadcn UI base components
│   ├── button.tsx
│   ├── input.tsx
│   ├── card.tsx
│   └── ...
├── navigation/               # Layout and navigation
│   ├── navbar.tsx
│   ├── sidebar.tsx
│   └── common/
│       └── heading.tsx       # H1-H6, P-P4 components
├── ext/                      # Extended/custom components
├── section.tsx               # Section layout component
└── ...                       # Other shared components

`src/lib/`

Utilities and library integrations:

lib/
├── auth/                     # Authentication utilities
│   ├── server.ts             # Server-side auth
│   └── client.ts             # Client-side hooks
├── errors/                   # Error handling
│   ├── custom-error.ts       # CustomError class
│   ├── translate-error.ts    # Error translation
│   └── use-translate-error.tsx
├── icons/                    # Icon registry
│   ├── index.tsx             # Icon component
│   ├── lucide.ts             # Lucide icons
│   ├── social.tsx            # Social icons
│   └── payment.tsx           # Payment icons
├── rate-limit/               # Rate limiting
├── server/                   # Server-only code
└── utils/                    # Utility functions

`src/i18n/` & `src/messages/`

Internationalization setup and translation files:

i18n/
├── config.tsx                # Locale configuration
├── request.ts                # Request-based locale
├── routing.ts                # Routing config
└── ...

messages/
├── dictionaries/
│   ├── en/                   # English translations
│   │   ├── common.json
│   │   ├── menu.json
│   │   ├── customErrors.json
│   │   ├── toasts.json
│   │   └── ...
│   └── it/                   # Italian translations
│       └── ...
└── zod-errors/               # Zod validation messages
    ├── en.json
    └── it.json

`src/routes/`

Declarative routing configuration:

routes/
├── index.ts                  # Auto-generated routes (DO NOT EDIT)
├── makeRoute.tsx             # Route builder
├── routing.ts                # Navigation & auth config
└── config/
    ├── icons.ts              # Page icon mapping
    └── ...

`src/config/`

Centralized configuration:

config/
├── app.ts                    # Main Config object
├── color-variants.ts         # Semantic colors + component variants
├── company.ts                # Company info
├── fonts.ts                  # Font configuration
└── storage.ts                # Storage buckets

File Naming Conventions

Pages & Routes

Page files: page.tsx
Route config: page.info.ts
Layouts: layout.tsx
Loading states: loading.tsx
Error boundaries: error.tsx

Components

React components: PascalCase.tsx
Client components: Include "use client" directive
Server components: No directive needed

Feature Files

Schemas: schema.ts
Functions: functions.ts
Hooks: hooks.ts
Fields: fields.tsx (client component)
Prompts: prompts.tsx (client component)

Database

Tables: kebab-case.ts (e.g., api-keys.ts)
Table names in DB: snake_case (e.g., api_keys)
Variable names: camelCase (e.g., apiKeys)

Configuration

Config files: kebab-case.ts
Environment: env-server.ts, env-client.ts

Import Aliases

Use path aliases for clean imports:

import { Button } from "@/components/ui/button";
import { api } from "@/rpc/react";
import { getAuth } from "@/lib/auth/server";
import Config from "@/config/app";

Next Steps

Architecture - Understand the tech stack
Patterns - Learn the 5-file pattern
Database - Work with tables and operations