# Coding Conventions

**Analysis Date:** 2026-04-27

## Naming Patterns

**Files:**
- Components: kebab-case (e.g., `character-sheet-page.tsx`, `add-condition-modal.tsx`, `hp-control.tsx`)
- Utilities/Services: kebab-case (e.g., `use-character-socket.ts`, `export-character-html.ts`)
- Directories: kebab-case (e.g., `features/`, `shared/`, `components/`)

**Functions:**
- camelCase for all function names
- Hooks prefixed with `use` (e.g., `useAuthStore`, `useCharacterSocket`, `useMemo`, `useState`)
- Event handlers prefixed with `handle` (e.g., `handleApply`, `handleConnection`, `handleDisconnect`)
- Getter/setter methods follow camelCase (e.g., `getToken()`, `setToken()`)

**Variables:**
- camelCase for all variable names
- Constants in UPPER_SNAKE_CASE (e.g., `PROFICIENCY_BONUS`, `SKILL_DATA`, `TABS`)
- Type unions with capitalized names (e.g., `CharacterType`, `AbilityType`, `TabType`)
- Boolean prefixes: `is`, `has`, `should`, `can` (e.g., `isLoading`, `isOwner`, `hasAccess`)

**Types:**
- PascalCase for all types, interfaces, and enums
- Domain types in shared: `Character`, `Campaign`, `User`, `CharacterItem`, `CharacterFeat`
- Props interfaces suffixed with `Props` (e.g., `HpControlProps`, `AddConditionModalProps`)
- DTO interfaces suffixed with `Dto` (e.g., `CreateCharacterDto`, `LoginDto`, `RegisterDto`)
- State types in Zustand: domain-specific (e.g., `AuthState`)

## Code Style

**Formatting:**
- Prettier configured in `server/.prettierrc` with:
  - Single quotes (`singleQuote: true`)
  - Trailing commas on all (`trailingComma: "all"`)
- Line length: implicit (Prettier default ~80 chars but allows overflow)
- Indentation: 2 spaces

**Linting:**
- Client: ESLint 9 with flat config (`eslint.config.js`)
  - Uses TypeScript ESLint recommended rules
  - React Hooks plugin with recommended rules
  - React Refresh plugin for Vite
  - No custom strict rules beyond defaults
- Server: ESLint 9 with flat config (`eslint.config.mjs`)
  - Uses TypeScript ESLint recommended rules with type checking (`recommendedTypeChecked`)
  - Prettier plugin for code formatting integration
  - **Important:** `@typescript-eslint/no-explicit-any` is **turned OFF** (line 29)
  - Warnings (not errors) for: `no-floating-promises`, `no-unsafe-argument`
  - Custom Prettier rule with `endOfLine: "auto"` for Windows compatibility

**TypeScript:**
- **Strict Mode Enforced** on client (`client/tsconfig.app.json`):
  - `"strict": true` ✓
  - `"noUnusedLocals": true` ✓
  - `"noUnusedParameters": true` ✓
  - `"noFallthroughCasesInSwitch": true` ✓
  - `"noUncheckedSideEffectImports": true` ✓
- Server TypeScript (`server/tsconfig.json`):
  - `"strictNullChecks": true` ✓
  - `"forceConsistentCasingInFileNames": true` ✓
  - `"noImplicitAny": false` (allows any, soft enforcement)
  - `"skipLibCheck": true` (skips lib type checking)

## Import Organization

**Order:** (observed pattern)
1. React/Framework imports (`react`, `react-router-dom`)
2. Third-party utilities (`zustand`, `axios`, `socket.io-client`)
3. NestJS/Framework imports (`@nestjs/*`)
4. Type-only imports (`type { ... }`)
5. Relative imports from shared (`@/shared/...`, `@/features/...`)
6. Decorators and metadata (after other imports)

**Path Aliases:**
- Client: `@/*` → `./src/*` (defined in `vite.config.ts` and `tsconfig.app.json`)
- Server: No path alias configured; uses relative paths
- Always use `@/` prefix on client to avoid relative path hell

**Module exports:**
- Barrel files used: `features/*/index.ts`, `shared/components/ui/index.ts`
- Default exports on pages: `export default App`
- Named exports for utilities, types, hooks: `export { HpControl }`, `export const api = new ApiClient()`

## Error Handling

**Philosophy (per CLAUDE.md):** No shortcuts. Proper error handling, not try/catch with console.log.

**Server-side (NestJS):**
- Use NestJS exception classes: `NotFoundException`, `ForbiddenException`, `UnauthorizedException`, `ConflictException`
- Access checks before operations (e.g., `checkCampaignAccess()`, `checkCharacterAccess()` in `characters.service.ts`)
- Return meaningful error messages: "Campaign not found", "No access to this campaign"
- Prisma operations wrapped in try-catch only when necessary for data validation
- JWT verification throws exceptions through guard: `JwtAuthGuard` handles 401s

**Client-side (React):**
- Axios interceptors for request/response handling (in `api.ts`)
- 401 errors trigger logout and redirect to `/login` (except auth endpoints)
- Error state in components: `isLoading`, `error`, `pendingChange` states
- Modal operations: try/catch with `setIsLoading(false)` in finally block
- Error logging: `console.error()` for debugging, no silent failures
- User feedback: Navigation on error (`navigate()`) or via error state

**Socket.io (WebSocket Gateway):**
- Token validation on connection (throws `client.disconnect()`)
- Logger for all connection/disconnection events
- Errors logged but don't crash server

## Logging

**Framework:** 
- Server: NestJS `Logger` (in modules/gateways)
  - E.g., `private logger = new Logger('CharactersGateway')`
  - Used for connection events, warnings, errors
- Client: `console.error()` for error debugging

**Patterns:**
- Server logs connection events with user context
- Client silently catches most errors, logs critical ones
- No debug logging infrastructure in place

## Comments

**When to Comment:**
- Constants with unclear meaning (e.g., `PROFICIENCY_BONUS` values, skill-to-ability mappings)
- Complex calculations (e.g., HP percentage calculations)
- Business logic that isn't immediately obvious (e.g., Pathfinder 2e rules)
- NOT used for obvious code ("increment counter")

**JSDoc/TSDoc:**
- Minimal usage observed
- API methods documented with Swagger decorators on server: `@ApiOperation()`, `@ApiResponse()`
- No runtime JSDoc comments in source

## Function Design

**Size:** 
- Modal components: 500-1700 lines (large, but feature-complete)
- Service methods: 10-50 lines (concise, focused)
- Utility functions: 5-20 lines

**Parameters:**
- Interface-based: Pass objects instead of multiple params
  - E.g., `onAdd(condition: { name: string; nameGerman: string; value?: number })`
  - DTO pattern on server: `CreateCharacterDto`, `LoginDto`
- Optional params with defaults: `remember: boolean = false`

**Return Values:**
- Async functions return typed Promises: `async getCharacter(): Promise<Character>`
- Component callbacks: callbacks are async promises (`onHpChange: (newHp: number) => Promise<void>`)
- Services return full domain objects with relations included

## Module Design

**Exports:**
- Components export as named: `export function HpControl() { ... }`
- Utilities export as named: `export const api = new ApiClient()`
- One export per file (generally)

**Barrel Files:**
- Used in features: `features/auth/index.ts` re-exports `useAuthStore`, `LoginPage`, `RegisterPage`
- Used for UI components: `shared/components/ui/index.ts` re-exports all buttons, cards, inputs
- Reduces import complexity

**Dependency Injection (Server):**
- NestJS @Injectable() decorator for services
- Constructor injection: `constructor(private prisma: PrismaService)`
- Circular dependencies resolved with @Inject(forwardRef()): seen in `CharactersService`

## State Management

**Client (Zustand):**
- Single store pattern: `create<AuthState>()`
- Persisted state with middleware: `persist()`
- Partialize: stores only non-sensitive fields (`user`, `isAuthenticated`)
- Actions as methods in store: `login()`, `logout()`, `checkAuth()`
- Error state in store: `error: string | null`

**Server (NestJS):**
- No client state management needed
- WebSocket gateway maintains connection map: `connectedClients = new Map()`

## Design Tokens (UI)

**Colors:**
- Primary: Magenta `#c26dbc` (in Tailwind as `primary-500`, `primary-600`, etc.)
- Secondary: Dark grays for dark mode (`secondary-800`, `secondary-700`)
- Text: Primary (light), secondary (dimmer), tertiary (dimmest)
- Background: Primary, secondary, tertiary layers
- Error: Red (`error-500`, `error-600`)
- Success: Green (`green-500`)
- Warning: Yellow (`yellow-500`)

**Typography:**
- Font sizes: sm, base, lg (Tailwind defaults)
- Weights: normal, medium (600), semibold
- All UI text in German except code/technical terms

**Icons:**
- Lucide React exclusively (e.g., `Heart`, `Swords`, `BookOpen`, `Package`)
- No emoji anywhere
- Icon sizes: `h-4 w-4` (standard), `h-6 w-6` (large)

**Touch Targets:**
- Minimum 44px (mobile-first, accessible)
- Buttons: `h-11` (44px), `h-9` (36px for small), `h-12` (48px for large)
- Icon buttons: `h-11 w-11` (44x44px)

**Spacing:**
- Tailwind v4 defaults: `p-4`, `gap-2`, `rounded-lg`, `rounded-2xl`
- Modals: `rounded-t-2xl sm:rounded-2xl` (bottom sheet on mobile, centered on desktop)

**Responsive:**
- Mobile-first breakpoints: `sm:` prefix for tablet+ (e.g., `sm:items-center`, `sm:rounded-2xl`)
- Flexbox for layouts: `flex`, `flex-col`, `items-center`, `justify-between`
- Grid rarely used

---

*Convention analysis: 2026-04-27*