A comprehensive collection of coding standards, best practices, and guidelines for the VerifyWise project. This documentation is designed to ensure consistency, maintainability, and quality across the entire codebase.

• New to the project? Start with QUICK_START.md
• Writing a PR? Use PR Checklist
• Creating a component? See Component Checklist

Core programming principles that apply across all languages and frameworks.

• Clean Code Principles - Meaningful names, small functions, Boy Scout Rule
• SOLID Principles - OOP design principles with TypeScript examples
• Design Principles - DRY, KISS, YAGNI, Clean Architecture

TypeScript-specific guidelines aligned with our ESLint configuration.

• TypeScript Standards - Strict mode, avoiding any, best practices
• Naming Conventions - Consistent naming across the codebase
• Type Safety - Utility types, type guards, generics

Frontend development standards for React applications.

• React Patterns - Function components, custom hooks, compound components
• Component Guidelines - File structure, MUI theme usage, accessibility
• Hooks Guidelines - Custom hook patterns, React Query integration
• State Management - Redux Toolkit, React Query, local state

Node.js and Express.js development standards.

• Express Patterns - Route organization, middleware, security
• Controller Guidelines - Request handling, validation, responses
• Middleware Guidelines - Authentication, error handling
• Database Patterns - Sequelize models, migrations, transactions

Python and FastAPI development guidelines.

• Python Standards - PEP 8 compliance, code organization
• FastAPI Patterns - Routers, Pydantic, dependency injection
• Type Hints - Type annotations, mypy compatibility

Security best practices aligned with OWASP guidelines.

• Security Checklist - OWASP-aligned security checklist
• Authentication - JWT handling, password security
• Input Validation - Validation strategies, sanitization
• Error Handling - Secure error handling, no internal exposure

Testing strategies and implementation guidelines.

• Testing Strategy - Test pyramid, TDD, coverage targets
• Frontend Testing - Vitest, React Testing Library
• Backend Testing - Jest, mocking patterns
• Python Testing - pytest, DeepEval for AI testing

Development workflow and collaboration guidelines.

• Git Workflow - Branching strategy, commit messages
• Code Review - Review focus areas, feedback format
• PR Guidelines - Pull request best practices
• Documentation - JSDoc, docstrings, component docs

Visual design standards extracted from the VerifyWise StyleGuide.

• Colors - Full color palette with theme tokens
• Typography - Font sizes, weights, line heights
• Spacing - 2px base unit, layout mixins
• Icons - lucide-react library, standard sizes
• Shadows, Animations & Z-Index - Elevation, transitions, layering
• Breakpoints - Responsive design patterns
• Component Patterns - Buttons, forms, tables, modals
• Do's and Don'ts - Quick reference design rules
• Accessibility - WCAG AA compliance guidelines
• Common Patterns - Reusable code patterns

Quick reference checklists for common tasks.

• PR Checklist - Pre-submission checklist
• Component Checklist - React component checklist
• API Endpoint Checklist - Backend endpoint checklist
• Security Review Checklist - Security review checklist

Copy-paste templates for common patterns.

• React Component Template
• Express Controller Template
• Custom Hook Template
• FastAPI Router Template

These guidelines are based on industry best practices from:

When updating these guidelines:

1. Ensure changes align with existing ESLint configuration
2. Provide concrete examples for each guideline
3. Include both good and bad examples where applicable
4. Update the relevant checklist if adding new requirements
5. Keep guidelines actionable and specific to VerifyWise

These guidelines align with existing project standards:

• ESLint Configuration: See Clients/eslint.config.js for enforced rules
• Clean Architecture: See Clients/clean-architecture.md for layer structure
• PR Template: See .github/pull_request_template.md for submission requirements