┌─────────────────────────────────────┐
│     Routes & Components             │  UI Layer
│     /src/routes/                    │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Server Functions                │  API Layer
│     /src/fn/                        │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Use Cases                       │  Business Logic
│     /src/use-cases/                 │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Data Access                     │  Database
│     /src/data-access/               │
└─────────────────────────────────────┘

// src/data-access/users.ts
import { database } from "~/db";
import { users } from "~/db/schema";
import { eq } from "drizzle-orm";
import type { User, UserCreate } from "~/db/schema";

export async function getUserById(id: number) {
  const result = await database
    .select()
    .from(users)
    .where(eq(users.id, id))
    .limit(1);
  return result[0];
}

export async function createUser(user: UserCreate) {
  const result = await database.insert(users).values(user).returning();
  return result[0];
}

export async function updateUser(id: number, user: Partial<UserCreate>) {
  const result = await database
    .update(users)
    .set({ ...user, updatedAt: new Date() })
    .where(eq(users.id, id))
    .returning();
  return result[0];
}

// src/use-cases/users.ts
import { getUserById, createUser, updateUser } from "~/data-access/users";
import { PublicError } from "./errors";
import type { UserCreate } from "~/db/schema";

export async function createUserUseCase(data: UserCreate) {
  // Business logic validation
  const existing = await getUserByEmail(data.email);
  if (existing) {
    throw new PublicError("Email already in use");
  }

  // Create user
  return createUser(data);
}

export async function updateUserProfileUseCase(
  userId: number,
  data: { name: string; bio?: string }
) {
  const user = await getUserById(userId);
  if (!user) {
    throw new PublicError("User not found");
  }

  return updateUser(userId, data);
}

// src/fn/users.ts
import { createServerFn } from "@tanstack/react-start";
import { authenticatedMiddleware, adminMiddleware } from "~/lib/auth";
import { z } from "zod";
import { updateUserProfileUseCase, getUserProfileUseCase } from "~/use-cases/users";

export const updateProfileFn = createServerFn()
  .middleware([authenticatedMiddleware])
  .inputValidator(
    z.object({
      name: z.string().min(1).max(100),
      bio: z.string().max(500).optional(),
    })
  )
  .handler(async ({ data, context }) => {
    return updateUserProfileUseCase(context.userId, data);
  });

export const getUserProfileFn = createServerFn()
  .middleware([authenticatedMiddleware])
  .handler(async ({ context }) => {
    return getUserProfileUseCase(context.userId);
  });

src/
├── routes/                 # File-based routing
│   ├── _layout.tsx        # Root layout
│   ├── index.tsx          # Home page
│   ├── courses/
│   │   ├── route.tsx      # /courses page
│   │   ├── $courseId/
│   │   │   └── route.tsx  # /courses/:courseId page
│   │   └── -components/   # Route-specific components
│   │       ├── CourseCard.tsx
│   │       └── CourseList.tsx
│   └── admin/
│       ├── route.tsx
│       └── -components/
├── components/            # Shared components
│   ├── ui/               # shadcn/ui components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   ├── page.tsx          # Page layout component
│   └── DefaultCatchBoundary.tsx
├── fn/                    # Server functions
│   ├── users.ts
│   ├── auth.ts
│   └── segments.ts
├── use-cases/            # Business logic
│   ├── users.ts
│   ├── segments.ts
│   └── errors.ts
├── data-access/          # Database queries
│   ├── users.ts
│   └── segments.ts
├── db/                   # Database config
│   ├── index.ts         # Database connection
│   ├── schema.ts        # Drizzle schema
│   ├── migrate.ts       # Migration runner
│   └── seed.ts          # Seed data
├── hooks/               # React hooks
│   ├── useAuth.ts
│   └── mutations/       # Mutation hooks
│       └── useUpdateProfile.ts
├── lib/                 # Utilities
│   ├── auth.ts         # Auth middleware
│   └── utils.ts        # cn() utility
├── config/             # Configuration
│   └── index.ts        # Magic numbers, feature flags
└── utils/              # Helpers
    ├── env.ts          # Environment variables
    └── storage.ts      # S3/R2 utilities

import { createFileRoute } from "@tanstack/react-router";
import { assertIsAdminFn } from "~/fn/auth";

export const Route = createFileRoute("/admin/users")({
  beforeLoad: () => assertIsAdminFn(),
  component: AdminUsersPage,
});

import { createFileRoute, redirect } from "@tanstack/react-router";

export const Route = createFileRoute("/dashboard")({
  beforeLoad: async ({ context }) => {
    if (!context.user) {
      throw redirect({ to: "/login" });
    }
  },
  component: DashboardPage,
});

// src/use-cases/errors.ts
export class PublicError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "PublicError";
  }
}

export class NotFoundError extends PublicError {
  constructor(resource: string) {
    super(`${resource} not found`);
  }
}

export class UnauthorizedError extends PublicError {
  constructor(message = "Unauthorized") {
    super(message);
  }
}

export async function getSegmentByIdUseCase(id: number) {
  const segment = await getSegmentById(id);
  if (!segment) {
    throw new NotFoundError("Segment");
  }
  return segment;
}

// src/config/index.ts
export const MAX_FILE_SIZE = 500 * 1024 * 1024; // 500MB
export const MAX_TITLE_LENGTH = 100;
export const PAGINATION_DEFAULT_LIMIT = 20;
export const SESSION_EXPIRY_DAYS = 30;

// Feature flags
export const FEATURE_FLAGS = {
  enableNewCheckout: false,
  enableAIFeatures: true,
};