✅ Good
app/user-profile/page.tsx
app/api/auth-callback/route.ts
app/admin/user-management/page.tsx

❌ Avoid
app/userProfile/page.tsx
app/user_profile/page.tsx
app/UserProfile/page.tsx

✅ Good
components/UserProfile.tsx
components/AuthButton.tsx
components/DashboardLayout.tsx

❌ Avoid
components/userProfile.tsx
components/auth-button.tsx
components/dashboard_layout.tsx

✅ Good
lib/formatDate.ts
hooks/useAuth.ts
lib/validateEmail.ts

❌ Avoid
lib/format-date.ts
hooks/use_auth.ts
lib/ValidateEmail.ts

✅ Good
lib/constants/API_ENDPOINTS.ts
config/DATABASE_CONFIG.ts
lib/constants/ERROR_MESSAGES.ts

❌ Avoid
lib/constants/apiEndpoints.ts
config/database-config.ts
lib/constants/errorMessages.ts

✅ Good
interface User {
  id: string;
  name: string;
  email: string;
}

type AuthState = 'authenticated' | 'unauthenticated' | 'loading';

interface CreateUserRequest {
  name: string;
  email: string;
}

❌ Avoid
interface user { ... }
type authState = string;
interface createUserReq { ... }

✅ Good - Feature-based
components/features/
├── auth/
│   ├── LoginForm.tsx
│   ├── SignupForm.tsx
│   └── AuthButton.tsx
├── dashboard/
│   ├── DashboardStats.tsx
│   ├── DashboardLayout.tsx
│   └── StatsCard.tsx
└── profile/
    ├── UserProfile.tsx
    ├── ProfileSettings.tsx
    └── AvatarUpload.tsx

❌ Avoid - File-type based
components/
├── forms/
│   ├── LoginForm.tsx
│   ├── SignupForm.tsx
│   └── ProfileForm.tsx
├── buttons/
│   ├── AuthButton.tsx
│   ├── SubmitButton.tsx
│   └── DeleteButton.tsx
└── layouts/
    ├── DashboardLayout.tsx
    └── ProfileLayout.tsx

✅ Good
components/features/dashboard/
├── DashboardStats.tsx
├── DashboardStats.test.tsx
├── DashboardStats.stories.tsx
└── dashboard-stats.module.css

❌ Avoid
components/DashboardStats.tsx
__tests__/DashboardStats.test.tsx
stories/DashboardStats.stories.tsx
styles/dashboard-stats.css

✅ Good
// 1. External libraries
import React from 'react';
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

// 2. Internal packages (monorepo)
import { Button } from '@packages/ui';
import { formatDate } from '@packages/utils';
import { db } from '@packages/database';

// 3. Local app imports (absolute paths)
import { auth } from '@/lib/auth';
import { validateUser } from '@/lib/validation';
import { UserCard } from '@/components/features/user/UserCard';

// 4. Relative imports (last resort)
import { helper } from './utils';
import './styles.css';

❌ Avoid
import { helper } from './utils';
import React from 'react';
import { Button } from '@packages/ui';
import { auth } from '@/lib/auth';

// packages/ui/src/index.ts
export { Button } from './components/button';
export { Card } from './components/card';
export { Input } from './components/input';
export { Modal } from './components/modal';

// Usage
import { Button, Card, Input } from '@packages/ui';

✅ Good - Named exports
// components/UserProfile.tsx
export function UserProfile({ user }: UserProfileProps) {
  return <div>{user.name}</div>;
}

// Usage
import { UserProfile } from '@/components/UserProfile';

✅ Acceptable - Default exports for pages
// app/profile/page.tsx
export default function ProfilePage() {
  return <UserProfile user={currentUser} />;
}

// 1. Imports (following import order)
import React from 'react';
import { Button } from '@packages/ui';
import { cn } from '@/lib/utils';

// 2. Types and interfaces
interface UserCardProps {
  user: {
    id: string;
    name: string;
    email: string;
    avatar?: string;
  };
  className?: string;
  onEdit?: () => void;
}

// 3. Component implementation
export function UserCard({ user, className, onEdit }: UserCardProps) {
  return (
    <div className={cn('rounded-lg border p-4', className)}>
      <div className="flex items-center space-x-3">
        {user.avatar && (
          <img
            src={user.avatar}
            alt={user.name}
            className="h-10 w-10 rounded-full"
          />
        )}
        <div>
          <h3 className="font-semibold">{user.name}</h3>
          <p className="text-sm text-muted-foreground">{user.email}</p>
        </div>
      </div>
      {onEdit && (
        <Button onClick={onEdit} className="mt-3">
          Edit Profile
        </Button>
      )}
    </div>
  );
}

// 4. Default props (if needed)
UserCard.defaultProps = {
  className: '',
};

✅ Good
interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'destructive';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
  onClick?: () => void;
}

❌ Avoid
interface ButtonProps {
  children: React.ReactNode;
  type?: string;
  big?: boolean;
  loading?: boolean;
  click?: () => void;
}

// Server Component (default - no directive)
import { db } from '@packages/database';

export async function UserList() {
  const users = await db.select().from(usersTable);
  
  return (
    <div>
      {users.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}

// Client Component (explicit directive)
'use client';

import { useState } from 'react';
import { Button } from '@packages/ui';

export function InteractiveButton() {
  const [count, setCount] = useState(0);
  
  return (
    <Button onClick={() => setCount(c => c + 1)}>
      Clicked {count} times
    </Button>
  );
}

// ✅ Good - Colocated types
// components/features/auth/LoginForm.tsx
interface LoginFormProps {
  onSuccess?: () => void;
  redirectTo?: string;
}

interface LoginFormData {
  email: string;
  password: string;
  rememberMe?: boolean;
}

export function LoginForm({ onSuccess, redirectTo }: LoginFormProps) {
  // Component implementation
}

// ✅ Good - Shared types in separate file
// lib/types/auth.types.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: 'user' | 'admin';
}

export interface AuthSession {
  user: User;
  token: string;
  expiresAt: Date;
}

// User entity
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
  updatedAt: Date;
}

// API types using utility types
type CreateUserRequest = Omit<User, 'id' | 'createdAt' | 'updatedAt'>;
type UpdateUserRequest = Partial<Pick<User, 'name' | 'email'>>;
type UserResponse = Pick<User, 'id' | 'email' | 'name'>;

✅ Good
interface ApiResponse<TData = unknown> {
  data: TData;
  success: boolean;
  message: string;
}

interface Repository<TEntity, TCreateInput, TUpdateInput> {
  create(input: TCreateInput): Promise<TEntity>;
  update(id: string, input: TUpdateInput): Promise<TEntity>;
  findById(id: string): Promise<TEntity | null>;
}

❌ Avoid
interface ApiResponse<T = any> {
  data: T;
  success: boolean;
  message: string;
}

✅ Good - Logical grouping
<div className="
  flex items-center justify-between
  w-full h-12 px-4 py-2
  bg-white border border-gray-200 rounded-lg
  text-sm font-medium text-gray-900
  hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-blue-500
  transition-colors duration-200
">

❌ Avoid - Random order
<div className="text-sm bg-white focus:ring-2 px-4 flex hover:bg-gray-50 border items-center w-full rounded-lg">

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'destructive' | 'ghost' | 'outline';
  size?: 'sm' | 'md' | 'lg';
}

const buttonVariants = {
  variant: {
    primary: 'bg-blue-600 text-white hover:bg-blue-700',
    secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
    destructive: 'bg-red-600 text-white hover:bg-red-700',
    ghost: 'hover:bg-gray-100 text-gray-900',
    outline: 'border border-gray-300 bg-white hover:bg-gray-50',
  },
  size: {
    sm: 'px-2 py-1 text-xs',
    md: 'px-4 py-2 text-sm',
    lg: 'px-6 py-3 text-base',
  },
};

// ✅ Good - Snake case for database
export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: text('email').notNull().unique(),
  firstName: text('first_name').notNull(),
  lastName: text('last_name').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const userSessions = pgTable('user_sessions', {
  id: uuid('id').primaryKey().defaultRandom(),
  userId: uuid('user_id').references(() => users.id).notNull(),
  token: text('token').notNull().unique(),
  expiresAt: timestamp('expires_at').notNull(),
});

❌ Avoid - Mixed naming conventions
export const Users = pgTable('Users', {
  ID: uuid('ID').primaryKey(),
  Email: text('Email').notNull(),
  firstName: text('firstName').notNull(),
  // Inconsistent naming
});

// ✅ Good - Descriptive names
export async function getUserById(userId: string) {
  return db.select().from(users).where(eq(users.id, userId));
}

export async function createUser(userData: CreateUserData) {
  return db.insert(users).values(userData).returning();
}

export async function updateUserEmail(userId: string, email: string) {
  return db
    .update(users)
    .set({ email, updatedAt: new Date() })
    .where(eq(users.id, userId));
}

❌ Avoid - Generic names
export async function getUser(id: string) { ... }
export async function createUser(data: any) { ... }
export async function updateUser(id: string, data: any) { ... }

// ✅ Good - Clear action purpose
export const updateUserProfile = actionClientUser
  .metadata({ name: 'updateUserProfile' })
  .schema(updateUserProfileSchema)
  .action(async ({ ctx: { userId }, parsedInput }) => {
    // Implementation
  });

export const deleteUserAccount = actionClientUser
  .metadata({ name: 'deleteUserAccount' })
  .schema(deleteUserAccountSchema)
  .action(async ({ ctx: { userId } }) => {
    // Implementation
  });

❌ Avoid - Generic names
export const userAction = actionClientUser.schema(schema).action(...);
export const doUserStuff = actionClientUser.schema(schema).action(...);

// ✅ Good - RESTful naming
// app/api/users/route.ts - GET /api/users (list users)
// app/api/users/[id]/route.ts - GET /api/users/123 (get user)
// app/api/users/[id]/profile/route.ts - PATCH /api/users/123/profile

// Route handlers
export async function GET(request: NextRequest) {
  // Get users
}

export async function POST(request: NextRequest) {
  // Create user
}

export async function PATCH(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  // Update user
}

❌ Avoid - Non-RESTful naming
// app/api/getUserById/route.ts
// app/api/createUser/route.ts
// app/api/updateUserData/route.ts

// lib/errors.ts
export class ValidationError extends Error {
  constructor(
    message: string,
    public field: string,
    public code: string = 'VALIDATION_ERROR'
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

export class DatabaseError extends Error {
  constructor(
    message: string,
    public operation: string,
    public code: string = 'DATABASE_ERROR'
  ) {
    super(message);
    this.name = 'DatabaseError';
  }
}

// Usage
if (!email) {
  throw new ValidationError('Email is required', 'email', 'REQUIRED_FIELD');
}

// app/error.tsx
'use client';

interface ErrorPageProps {
  error: Error & { digest?: string };
  reset: () => void;
}

export default function Error({ error, reset }: ErrorPageProps) {
  return (
    <div className="flex flex-col items-center justify-center min-h-[400px]">
      <h2 className="text-lg font-semibold text-gray-900 mb-2">
        Something went wrong!
      </h2>
      <p className="text-sm text-gray-600 mb-4">
        {error.message || 'An unexpected error occurred'}
      </p>
      <button
        onClick={() => reset()}
        className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
      >
        Try again
      </button>
    </div>
  );
}

/**
 * Formats a date according to the user's locale preferences
 * @param date - The date to format
 * @param locale - Optional locale override (defaults to 'en-US')
 * @param options - Intl.DateTimeFormat options
 * @returns Formatted date string
 * 
 * @example
 * ```typescript
 * formatDate(new Date(), 'en-US', { dateStyle: 'medium' })
 * // Returns: "Jan 15, 2024"
 * ```
 */
export function formatDate(
  date: Date,
  locale: string = 'en-US',
  options: Intl.DateTimeFormatOptions = {}
): string {
  return new Intl.DateTimeFormat(locale, options).format(date);
}

/**
 * UserCard displays user information in a card format
 * 
 * @example
 * ```tsx
 * <UserCard 
 *   user={{ id: '1', name: 'John', email: 'john@example.com' }}
 *   onEdit={() => console.log('Edit clicked')}
 * />
 * ```
 */
interface UserCardProps {
  /** User object containing id, name, email, and optional avatar */
  user: {
    id: string;
    name: string;
    email: string;
    avatar?: string;
  };
  /** Additional CSS classes */
  className?: string;
  /** Callback fired when edit button is clicked */
  onEdit?: () => void;
}

export function UserCard({ user, className, onEdit }: UserCardProps) {
  // Implementation
}

// .eslintrc.js
module.exports = {
  extends: ['@packages/eslint-config/next'],
  rules: {
    // Naming conventions
    'camelcase': ['error', { 'properties': 'never' }],
    '@typescript-eslint/naming-convention': [
      'error',
      {
        'selector': 'interface',
        'format': ['PascalCase'],
        'custom': {
          'regex': '^I[A-Z]',
          'match': false
        }
      }
    ]
  }
};