Project Overview

This project follows strict TypeScript/Node.js/React development principles with emphasis on functional programming, clean architecture, and type safety.

Architecture Principles

• Business logic completely outside components and states
• Functional programming approach without classes
• Layer-based project structure
• Maximum TypeScript strictness
• Pragmatic library selection (no rigid stack)

Folder Structure

• /src/components/ - Reusable UI components
• /src/hooks/ - Custom React hooks (rarely used)
• /src/services/ - API and external services
• /src/stores/ - Nanostores state management
• /src/utils/ - Pure utility functions
• /src/types/ - TypeScript type definitions
• Business domain types separately
• UI types next to components
• Shared types in dedicated files

Technology Stack

• Frontend: React with Nanostores
• Backend: NestJS or Fastify
• Validation: Zod schema validation
• Testing: Vitest for unit tests
• Linting: ESLint + Prettier
• No Husky/lint-staged - rely on CI and manual checks

TypeScript Standards

• Complete ban on any type
• Rare use of unknown type
• Prefer enum over union types
• Maximum strict compiler flags
• Consistent use of type vs interface (choose one per project)
• No barrel files - use explicit relative imports

React Standards

• Only function components with hooks
• Business logic in pure functions and services
• State management with Nanostores
• Rare custom hooks - prefer pure functions
• Self-documenting code over comments
• JSDoc only for complex algorithms or public APIs

Backend Standards

• Explicit error handling with try/catch in each handler
• Async/await everywhere possible
• Pure functions for business logic
• Zod validation for all incoming data

Code Quality

• Self-documenting code as primary approach
• Clear naming for variables and functions
• Single responsibility for functions and components
• Unit tests for functions and services with Vitest
• Pure function testing without side effects

Key Rules

// BUSINESS LOGIC OUTSIDE COMPONENTS
const CartTotal = () => {
  const items = useStore($cartItems);
  const total = calculateTotal(items); // Pure function
  return <div>Total: {total}</div>;
};

// NO ANY, EXPLICIT TYPING
function processData(data: unknown) {
  if (typeof data === 'string') {
    return data.toUpperCase();
  }
  return '';
}

// CLEAN SELF-DOCUMENTING CODE
const isUserActive = user.status === UserStatus.ACTIVE;

Testing Approach

• Unit tests for functions and services only
• Vitest framework (not Jest)
• Mock dependencies for service testing
• Pure function testing without side effects

Documentation

• Prefer self-documenting code over comments
• JSDoc only when absolutely necessary
• Clear, descriptive function and variable names
• No redundant comments for obvious code