# Coding Standards

**Last Updated:** January 2025  
**Project:** Moyos Wedding App

---

## File and Folder Naming

### Files
- **Components:** `kebab-case.tsx` (e.g., `rsvp-form.tsx`, `guest-card.tsx`)
- **Utilities:** `kebab-case.ts` (e.g., `request-id.ts`, `rate-limit.ts`)
- **API Routes:** `route.ts` (Next.js App Router convention)
- **Types:** `kebab-case.ts` or in feature folders as `types.ts`

### Folders
- **Feature folders:** `kebab-case` (e.g., `rsvp/`, `guestbook/`)
- **Component folders:** `kebab-case` (e.g., `features/`, `ui/`)
- **Utility folders:** `kebab-case` (e.g., `lib/`, `hooks/`)

---

## Type Definitions

### Location
- **Global types:** `src/types/index.ts`
- **Feature-specific types:** Co-located in feature folders (e.g., `src/components/features/rsvp/types.ts`)
- **API types:** Co-located with API routes or in `src/types/api.ts`

### Naming
- **Interfaces:** `PascalCase` (e.g., `GuestSession`, `RsvpFormData`)
- **Types:** `PascalCase` (e.g., `ApiResponse<T>`, `AuditEventType`)
- **Enums:** `PascalCase` (e.g., `ReportType`, `ExportFormat`)

---

## Hooks

### Naming
- **All hooks:** Must be prefixed with `use` (e.g., `useGuest`, `useRealtime`, `useMobile`)
- **File names:** `use-kebab-case.ts` (e.g., `use-guest.ts`, `use-realtime.ts`)

### Location
- **Global hooks:** `src/hooks/`
- **Feature-specific hooks:** Co-located in feature folders (e.g., `src/components/features/rsvp/use-rsvp.ts`)

---

## Components

### Naming
- **Component files:** `kebab-case.tsx` (e.g., `rsvp-form.tsx`)
- **Component names:** `PascalCase` (e.g., `RsvpForm`, `GuestCard`)
- **Props interfaces:** `ComponentNameProps` (e.g., `RsvpFormProps`)

### Organization
- **Feature components:** `src/components/features/{feature-name}/`
- **UI components:** `src/components/ui/`
- **Layout components:** `src/components/layout/`

---

## API Routes

### Structure
- **Route handlers:** `src/app/api/{route}/route.ts`
- **Request validation:** Use Zod schemas in `src/lib/validators/`
- **Error handling:** Standardized error responses
- **Logging:** Use `logger` with request ID context

### Naming
- **Route files:** `route.ts` (Next.js convention)
- **Validator files:** `{feature}-validators.ts` (e.g., `rsvp-validators.ts`)

---

## State Management

### Single Source of Truth
- **Guest state:** `src/context/guest-context.tsx`
- **Admin state:** To be centralized (currently scattered)
- **No duplicate state:** Avoid storing same data in multiple places

---

## Imports

### Order
1. React/Next.js imports
2. Third-party library imports
3. Internal component imports
4. Internal utility imports
5. Type imports (with `type` keyword)
6. Relative imports

### Example
```typescript
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { verifyGuestSession } from '@/lib/auth';
import { logger } from '@/lib/logger';
import type { GuestSession } from '@/types';
```

---

## Code Style

### TypeScript
- **No `any` types:** Use proper types or `unknown`
- **Strict mode:** Enabled
- **Type imports:** Use `import type` for type-only imports

### Functions
- **Async functions:** Always handle errors with try-catch
- **Error logging:** Use `logger.error()` with context
- **Request ID:** Include in all log contexts

### Validation
- **All API inputs:** Must use Zod validation
- **Schemas:** Co-located in `src/lib/validators/`

---

## Testing

### File Naming
- **Unit tests:** `*.test.ts` or `*.test.tsx`
- **E2E tests:** `*.spec.ts`
- **Location:** Co-located with source files in `__tests__/` folders

### Coverage
- **Minimum:** 60% global coverage
- **Critical utilities:** 100% coverage (sanitize, csrf, rate-limit)
- **API routes:** 80%+ coverage

---

## Documentation

### Comments
- **Complex logic:** Add explanatory comments
- **API routes:** JSDoc comments for exported functions
- **Types:** Document complex types with comments

### README Files
- **Feature folders:** Optional `README.md` for complex features
- **Main docs:** In `docs/` folder

---

## Git Commits

### Format
- **Type:** `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`
- **Scope:** Optional feature name
- **Message:** Clear, concise description

### Examples
- `feat: add request ID tracking to middleware`
- `fix: correct Zod validation error handling`
- `chore: remove unused @sendgrid/mail dependency`
- `refactor: consolidate duplicate RSVP form components`

---

## Security

### Secrets
- **Never commit:** `.env.local`, `.env.production`
- **Always validate:** Use Zod schemas for env variables
- **No client-side secrets:** Never use `NEXT_PUBLIC_*` for secrets

### Input Validation
- **All inputs:** Validate with Zod
- **File uploads:** Validate magic bytes, size, type
- **Sanitization:** Use `sanitize.ts` utilities

---

## Performance

### Code Splitting
- **Large components:** Use `next/dynamic` for lazy loading
- **Admin components:** Always lazy loaded
- **Heavy libraries:** Lazy load when possible

### Caching
- **API responses:** Use SWR for client-side caching
- **Database queries:** Add indexes, optimize queries
- **Static data:** Cache in Redis when available

---

## Accessibility

### ARIA Labels
- **Interactive elements:** Always include aria-labels
- **Form inputs:** Associated labels
- **Error messages:** Announced to screen readers

### Keyboard Navigation
- **All interactive elements:** Keyboard accessible
- **Focus management:** Proper focus handling

---

**This document should be updated as patterns evolve.**