books/docs/architecture/coding-standards.md

Coding Standards

Critical Fullstack Rules

• API Error Handling: All API routes must use the centralized error handler middleware. Never send raw errors to clients.

• Input Validation: All POST/PUT endpoints must validate inputs using express-validator. Frontend should also validate before sending.

• Database Access: Always use Prisma ORM for database operations. Never write raw SQL queries (except for complex queries Prisma can't handle).

• Environment Variables: Access environment variables only through centralized config. Never use process.env or import.meta.env directly in components/controllers.

• Date Handling: Use date-fns for all date manipulation. Never use vanilla JavaScript Date methods for calculations.

• Component Structure: React components must be functional with hooks. No class components.

• State Updates: Never mutate state directly. Use setState/setters or Context dispatch actions.

• API Calls: Never make direct fetch calls in components. Always use the service layer (booksService, logsService).

• Error Boundaries: Critical routes must have React Error Boundaries to catch and display errors gracefully.

• Prisma Schema Changes: Never modify database directly. Always create Prisma migrations for schema changes.

Naming Conventions

Element	Frontend	Backend	Example
Components	PascalCase	-	BookCard.jsx, LogProgressModal.jsx
Hooks	camelCase with 'use' prefix	-	useBooks.js, useProgress.js
Services	camelCase with 'Service' suffix	camelCase with 'Service' suffix	booksService.js, openLibraryService.js
Controllers	-	camelCase with 'Controller' suffix	booksController.js
API Routes	-	kebab-case	/api/books, /api/books/:id/logs
Database Tables	-	PascalCase (Prisma convention)	Book, ReadingLog
Files	kebab-case	kebab-case	book-card.jsx, pace-calculation-service.js
CSS Classes	kebab-case (Tailwind)	-	text-blue-500, book-card-container
Functions	camelCase	camelCase	calculateRequiredPace(), handleLogClick()
Constants	SCREAMING_SNAKE_CASE	SCREAMING_SNAKE_CASE	API_BASE_URL, MAX_QUERY_LENGTH

---