gh-cskiro-claudex/skills/analysis/bulletproof-react-auditor/reference/audit_criteria.md

# Bulletproof React Audit Criteria

Complete checklist for auditing React/TypeScript applications against Bulletproof React architecture principles.

## 1. Project Structure

### Feature-Based Organization
- [ ] 80%+ of code organized in src/features/
- [ ] Each feature has its own directory
- [ ] Features are independent (no cross-feature imports)
- [ ] Feature subdirectories: api/, components/, hooks/, stores/, types/, utils/

### Top-Level Directories
- [ ] src/app/ exists (application layer)
- [ ] src/features/ exists and contains features
- [ ] src/components/ for truly shared components only
- [ ] src/hooks/ for shared custom hooks
- [ ] src/lib/ for third-party configurations
- [ ] src/utils/ for shared utilities
- [ ] src/types/ for shared TypeScript types
- [ ] src/stores/ for global state (if needed)

### Unidirectional Dependencies
- [ ] No cross-feature imports
- [ ] Shared code imported into features (not vice versa)
- [ ] App layer imports from features
- [ ] Clean dependency flow: shared → features → app

## 2. Component Architecture

### Component Design
- [ ] Components < 300 lines of code
- [ ] No large components (> 500 LOC)
- [ ] Components accept < 7-10 props
- [ ] No nested render functions
- [ ] Component colocation (near where used)
- [ ] Proper use of composition over excessive props

### File Organization
- [ ] Kebab-case file naming
- [ ] Components colocated with tests
- [ ] Styles colocated with components
- [ ] Feature-specific components in features/
- [ ] Only truly shared components in src/components/

### Abstraction
- [ ] No premature abstractions
- [ ] Repetition identified before creating abstractions
- [ ] Components are focused and single-purpose

## 3. State Management

### State Categories
- [ ] Component state with useState/useReducer
- [ ] Global state with Context, Zustand, or Jotai
- [ ] Server cache state with React Query or SWR
- [ ] Form state with React Hook Form or Formik
- [ ] URL state with React Router

### State Localization
- [ ] State as local as possible
- [ ] Global state only when necessary
- [ ] No single massive global state object
- [ ] Context split into multiple focused providers

### Server State
- [ ] React Query or SWR for API data
- [ ] Proper caching configuration
- [ ] No manual loading/error state for API calls
- [ ] Optimistic updates where appropriate

## 4. API Layer

### Centralized Configuration
- [ ] Single API client instance
- [ ] Configured in src/lib/
- [ ] Base URL configuration
- [ ] Request/response interceptors
- [ ] Error handling interceptors

### Request Organization
- [ ] API calls colocated in features/*/api/
- [ ] Type-safe request declarations
- [ ] Custom hooks for each endpoint
- [ ] Validation schemas with types
- [ ] Proper error handling

## 5. Testing Strategy

### Coverage
- [ ] 80%+ line coverage
- [ ] 75%+ branch coverage
- [ ] 100% coverage on critical paths
- [ ] Coverage reports generated

### Testing Trophy Distribution
- [ ] ~70% integration tests
- [ ] ~20% unit tests
- [ ] ~10% E2E tests

### Test Quality
- [ ] Tests named "should X when Y"
- [ ] Semantic queries (getByRole, getByLabelText)
- [ ] Testing user behavior, not implementation
- [ ] No brittle tests (exact counts, element ordering)
- [ ] Tests isolated and independent
- [ ] No flaky tests

### Testing Tools
- [ ] Vitest or Jest configured
- [ ] @testing-library/react installed
- [ ] @testing-library/jest-dom for assertions
- [ ] Playwright or Cypress for E2E (optional)

## 6. Styling Patterns

### Styling Approach
- [ ] Consistent styling method chosen
- [ ] Component library (Chakra, Radix, MUI) OR
- [ ] Utility CSS (Tailwind) OR
- [ ] CSS-in-JS (Emotion, styled-components)
- [ ] Styles colocated with components

### Design System
- [ ] Design tokens defined
- [ ] Color palette established
- [ ] Typography scale defined
- [ ] Spacing system consistent

## 7. Error Handling

### Error Boundaries
- [ ] Multiple error boundaries at strategic locations
- [ ] Route-level error boundaries
- [ ] Feature-level error boundaries
- [ ] User-friendly error messages
- [ ] Error recovery mechanisms

### API Errors
- [ ] API error interceptors configured
- [ ] User notifications for errors
- [ ] Automatic retry logic where appropriate
- [ ] Unauthorized user logout

### Error Tracking
- [ ] Sentry or similar service configured
- [ ] User context added to errors
- [ ] Environment-specific error handling
- [ ] Source maps configured for production

## 8. Performance

### Code Splitting
- [ ] React.lazy() for route components
- [ ] Suspense boundaries with loading states
- [ ] Large features split into chunks
- [ ] Bundle size monitored and optimized

### React Performance
- [ ] State localized to prevent re-renders
- [ ] React.memo for expensive components
- [ ] useMemo for expensive calculations
- [ ] useCallback for stable function references
- [ ] Children prop optimization patterns

### Asset Optimization
- [ ] Images lazy loaded
- [ ] Images in modern formats (WebP)
- [ ] Responsive images with srcset
- [ ] Images < 500KB
- [ ] Videos lazy loaded or streamed

## 9. Security

### Authentication
- [ ] JWT stored in HttpOnly cookies (not localStorage)
- [ ] Secure session management
- [ ] Token refresh logic
- [ ] Logout functionality

### Authorization
- [ ] RBAC or PBAC implemented
- [ ] Protected routes
- [ ] Permission checks on actions
- [ ] API-level authorization

### XSS Prevention
- [ ] Input sanitization (DOMPurify)
- [ ] No dangerouslySetInnerHTML without sanitization
- [ ] Output encoding
- [ ] Content Security Policy

### CSRF Protection
- [ ] CSRF tokens for state-changing requests
- [ ] SameSite cookie attribute
- [ ] Verify origin headers

## 10. Standards Compliance

### ESLint
- [ ] .eslintrc or eslint.config.js configured
- [ ] React rules enabled
- [ ] TypeScript rules enabled
- [ ] Accessibility rules (jsx-a11y)
- [ ] Architectural rules (import restrictions)

### TypeScript
- [ ] strict: true in tsconfig.json
- [ ] No `any` types
- [ ] Explicit return types
- [ ] Type definitions for third-party libraries
- [ ] Types colocated with features

### Prettier
- [ ] Prettier configured
- [ ] Format on save enabled
- [ ] Consistent code style
- [ ] .prettierrc configuration

### Git Hooks
- [ ] Husky configured
- [ ] Pre-commit linting
- [ ] Pre-commit type checking
- [ ] Pre-commit tests (optional)

### File Naming
- [ ] Kebab-case for files and directories
- [ ] Consistent naming conventions
- [ ] ESLint rule to enforce naming

### Absolute Imports
- [ ] TypeScript paths configured (@/ prefix)
- [ ] Imports use @/ instead of relative paths
- [ ] Easier refactoring and moving files

## Compliance Scoring

### Grade Scale
- **A (90-100)**: Excellent Bulletproof React compliance
- **B (80-89)**: Good compliance, minor improvements needed
- **C (70-79)**: Moderate compliance, significant refactoring recommended
- **D (60-69)**: Poor compliance, major architectural changes needed
- **F (<60)**: Non-compliant, complete restructuring required

### Category Weights
All categories weighted equally for overall score.

---

**Note**: This checklist represents the ideal Bulletproof React architecture. Adapt based on your project's specific needs and constraints while maintaining the core principles.