• frontend/ → Next.js (React + Vite can be used for smaller projects, but Next.js is chosen for scalability, SSR/SSG, routing, and SEO).
• backend/ → Node.js + Express + MongoDB, fully in TypeScript, with ES Modules ("type": "module").

Framework: Next.js (with App Router) for scalability.

Styling: TailwindCSS + shadcn/ui for components.

shadcn/ui Standards:

• Use "new-york" style with CSS variables
• Lucide icons for all iconography
• Components in @/components/ui/ directory
• Always use provided variants and sizes
• Extend components by composition, not modification
• Use cn() utility for conditional classes

NEVER use mock/dummy data - Always fetch real data from API endpoints using React Query hooks.

State Management: React Query (TanStack) for server data + Context API/Zustand for global UI state.

API requests via a typed Axios client with interceptors.

UI/UX Standards:

• Always implement loading states using our enhanced Button component with loading prop
• Use toast notifications for user feedback (success/error messages)
• Implement proper form validation with real-time feedback
• Use skeleton loaders while content is loading
• Ensure all interactive elements provide immediate visual feedback

Directory structure: frontend/ src/ app/ # Next.js App Router (routes, pages, layouts) components/ # Reusable UI components features/ # Feature-specific components (e.g., ideas, users) hooks/ # Custom React hooks lib/ # API clients, utils, config store/ # State management (Zustand/Context) types/ # Global TypeScript interfaces

Best Practices:

• Use functional components only.

• Each component ≤ 150 lines.

• Always use props interfaces with TypeScript.

• Write utility functions separately in lib/ instead of inside components.

• Favor composition over inheritance.

• Use lazy loading / code splitting for heavy components.

• Loading States: Always use the enhanced Button component for forms:

  <Button loading={mutation.isPending} loadingText="Processing..." disabled={!isValid}>
    Submit
  </Button>

• Error Handling: Use toast notifications for all user feedback:

  toast({
    title: 'Success!',
    description: 'Operation completed successfully',
  });

• Use DTOs (Data Transfer Objects) for request/response typing.

• Always validate input with Zod schemas - follow existing patterns in validation/ folder.

• Use async error handling middleware (no try/catch in every controller).

• Error handling: Use AppError class for operational errors:

  throw new AppError('Resource not found', 404);

• Separate:

  • Controller → Handles req/res, delegates to services
  • Service → Business logic, data processing
  • Model → Database schema and validations

• Use index.ts barrels in folders for cleaner imports.

• Never mix DB queries directly in controllers.

• Validation patterns: Always clean and validate data:

  // Clean undefined arrays before sending
  const cleanData = {
    title: data.title.trim(),
    tags: data.tags?.length > 0 ? data.tags : undefined,
  };

Package manager: pnpm (monorepo friendly).

Use Docker for containerization.

Add GitHub Actions CI/CD with lint + test on every PR.

Add commit hooks (Husky + lint-staged).

Development Scripts:

• pnpm dev - Start both frontend and backend in development
• pnpm build - Build both packages for production
• pnpm seed - Seed database with sample data
• pnpm db:migrate - Run database migrations
• pnpm lint - Run ESLint across all packages
• pnpm test - Run all tests

Workspace Structure:

• Root level scripts handle cross-package commands
• Use --filter flag to target specific packages
• Shared dependencies managed at workspace root

Prettier Configuration:

• Semi-colons: true
• Single quotes: true
• Print width: 100
• Tab width: 2 spaces
• Trailing commas: es5

ESLint Rules:

• Unused vars: error (except args starting with _)
• any type: warn (minimize usage)
• No explicit return types required for functions
• Non-null assertions: warn

Naming conventions:

• Variables & functions → camelCase
• Classes & types → PascalCase
• Constants → UPPER_SNAKE_CASE

File naming: kebab-case.ts for files.

Folder naming: lowercase (e.g., controllers, models).

Consistent Response Format:

// Success responses
{
  "success": true,
  "data": { /* response data */ },
  "message": "Operation successful"
}

// Error responses
{
  "success": false,
  "error": "Error message",
  "message": "User-friendly message",
  "statusCode": 400
}

Pagination Standard:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10,
    "hasNext": true,
    "hasPrev": false
  }
}

API Client Configuration:

• Use axios with interceptors for auth and error handling
• Base URL from environment variables
• Credentials included for cookie-based auth
• Consistent error response handling