> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builderbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Guide

> This guide outlines the best practices and patterns to follow when developing with the Builder Box.

## Code Organization

### Feature Development

When adding new features:

1. Create a new directory in `src/features/`
2. Add feature-specific components and subcomponents
3. Keep components focused and reusable

Example structure:

```
features/
├── auth/
├── chat/
└── dashboard/
```

### Component Development

Components should follow these guidelines:

1. Use TypeScript for all components
2. Implement proper prop types
3. Use shadcn/ui components when possible
4. Follow atomic design principles

Example:

```tsx theme={null}
// components/ui/Button.tsx
import { ButtonProps } from '@/types'
import { cn } from '@/utils'

export const Button = ({ className, ...props }: ButtonProps) => {
  return (
    <button
      className={cn(
        'rounded-md bg-primary px-4 py-2 text-white',
        className
      )}
      {...props}
    />
  )
}
```

## State Management

### When to Use What

1. **React Context**
   * Global UI state
   * Theme preferences
   * Auth state

2. **tRPC + React Query**
   * Server state
   * Data fetching
   * Real-time updates

## API Development

### tRPC Router Structure

```typescript theme={null}
// routers/user.ts
import { z } from 'zod'
import { publicProcedure, router } from '../trpc'

export const userRouter = router({
  getProfile: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input, ctx }) => {
      // Implementation
    }),
})
```

### Error Handling

1. Use custom error classes
2. Implement proper error boundaries
3. Handle API errors gracefully

## Database Operations

### Prisma Best Practices

1. Use transactions for related operations
2. Implement proper error handling
3. Use type-safe queries
4. Follow naming conventions

Example:

```typescript theme={null}
// services/user.ts
import { prisma } from '@/lib/prisma'

export const userService = {
  async createUser(data: CreateUserInput) {
    return prisma.$transaction(async (tx) => {
      const user = await tx.user.create({
        data: {
          ...data,
          profile: {
            create: {
              // Profile data
            }
          }
        }
      })
      return user
    })
  }
}
```

## Styling Guidelines

### Tailwind CSS

1. Use utility classes
2. Follow the design system
3. Use CSS variables for theming
4. Implement responsive design

Example:

```tsx theme={null}
<div className="
  flex flex-col
  space-y-4
  p-4
  md:flex-row md:space-x-4 md:space-y-0
">
  {/* Content */}
</div>
```

### Component Styling

1. Use CSS Modules for complex styles
2. Implement dark mode support
3. Follow accessibility guidelines

## Performance

### Optimization Techniques

1. Use proper image optimization
2. Implement code splitting
3. Optimize bundle size
4. Use proper caching strategies

## Security

### Best Practices

1. Implement proper authentication
2. Use secure headers
3. Sanitize user input
4. Follow [OWASP](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/) guidelines

### Environment Variables

1. Use proper secrets management
2. Implement environment validation
3. Use different configs per environment
4. Document all variables in .env.example