Coding Guidelines

Core conventions enforced across the Renewa One codebase. These are non-negotiable standards for all contributors.

KISS Principle

• Simplest solution always — no over-engineering for hypothetical needs
• Fixed conventions over configuration — same pattern everywhere
• Follow industry standards — flag deviations and get explicit confirmation

Naming Rules

Rule	Details
Language	English-only identifiers (variables, functions, DB columns, JSON keys, enums, API paths)
Exceptions	Translation fields (nameDe, nameEn), i18n display text, German proper nouns in comments/data
Environments	Full names: development, staging, production — never dev/prod
Secrets	Environment-scoped, no suffixes: DATABASE_URL, JWT_SECRET
Secret exception	Semantic suffix for purpose: DATABASE_URL_MIGRATION

XSS Protection (MANDATORY)

All user-facing text fields must use sanitization helpers from backend/src/lib/sanitization-helpers.ts:

import { strictTextField, sanitizedLocalizedText, optionalSanitizedLocalizedText } from '@/lib/sanitization-helpers';
 
const schema = z.object({
  label: sanitizedLocalizedText(255),
  description: optionalSanitizedLocalizedText(1000),
  internalNote: strictTextField(500),
});

See Validation Pattern for full sanitization levels.

LocalizedText Pattern

All bilingual database fields use the LocalizedText type from Shared Layer:

// DB column: jsonb('name').$type<LocalizedText>().notNull()
// Zod schema: name: sanitizedLocalizedText(100)

NEVER: Flat columns (nameDe/nameEn), JSONB without .$type<LocalizedText>(), separate Zod fields per language.

Security

• Never write secrets to files or pass via CLI arguments
• Always use GitHub Environment Secrets — see CI-CD Workflows
• Never use --no-verify to skip git hooks — see Git Workflow
• Passwords: 12+ characters minimum
• Auth hashing: Bun.password.hash() (argon2id) — no separate argon2 packages

Code Quality Gates

Gate	Tool
Format + lint	Pre-commit hook (staged files only)
Typecheck	Pre-push hook + CI
Tests	Pre-push hook (affected only) + CI (full suite)
Security scan	CI — see Security Scanning

Related Patterns

• Service Layer Pattern — backend architecture
• Component Decomposition — frontend file structure
• State Management — choosing the right state tool
• React Query Pattern — server state management
• URL State Management — URL-synced UI state
• API Layer Pattern — frontend-backend communication
• Dependency Injection — service wiring
• Error Handling Pattern — error propagation
• Validation Pattern — input validation and sanitization
• Background Jobs — async processing
• Middleware Stack — request pipeline
• Shared Layer — cross-boundary types
• Git Workflow — branching and commit rules