code-organization

Code Organization

Systematic patterns for organizing code into maintainable, scalable structures.

Quick Start

Analyze project structure:

Review this project's file organization and suggest improvements

Set up new project:

Help me organize a new React/Node/Python project with proper structure

Identify module boundaries:

Analyze this codebase and identify where module boundaries should be

Capabilities

1. File Structure Patterns

Standard layouts by framework type.

React/Frontend Projects

project/
  src/
    components/           # Reusable UI components
      Button/
        Button.tsx
        Button.test.tsx
        Button.styles.ts
        index.ts
    features/             # Feature-based modules
      auth/
        components/
        hooks/
        api/
        types.ts
        index.ts
    hooks/                # Shared custom hooks
    utils/                # Utility functions
    services/             # API/external services
    stores/               # State management
    types/                # Shared TypeScript types
    App.tsx
    main.tsx
  tests/

Node.js/Backend Projects

project/
  src/
    api/
      v1/
        users/
          controller.ts
          service.ts
          repository.ts
          routes.ts
    config/
    middleware/
    models/
    services/
    utils/
    index.ts
  tests/

Python Projects

project/
  src/
    package_name/
      __init__.py
      api/
      core/
      models/
      services/
      utils/
      config.py
  tests/

See references/project-layouts.md for complete layouts.

2. Module Boundaries

Signs of Good Boundaries

Signs of Poor Boundaries

Creating Module Boundaries

// BEFORE: No clear boundaries
src/
  components/
    UserProfile.tsx      // Mixes auth, user data, UI
    LoginForm.tsx
  api/
    users.ts
    auth.ts

// AFTER: Clear domain boundaries
src/
  features/
    auth/
      components/
      hooks/
      api/
      types.ts
      index.ts          # Public API
    users/
      components/
      hooks/
      api/
      types.ts
      index.ts          # Public API

See references/module-patterns.md for complete patterns.

3. Naming Conventions

Avoid These Patterns

// BAD: Generic names
utils.ts, helpers.ts, misc.ts

// BAD: Numbered files
component1.tsx, handler2.ts

// BAD: Inconsistent casing
userProfile.tsx, user_settings.tsx

// BAD: Unclear abbreviations
usr.ts, auth_mgr.ts, btn.tsx

See references/naming-conventions.md for complete guide.

4. Directory Organization

When to Create Subdirectories

Co-location Pattern

// Component co-location
UserProfile/
  UserProfile.tsx
  UserProfile.test.tsx
  UserProfile.styles.ts
  useUserProfile.ts
  index.ts

// Feature co-location
features/
  checkout/
    components/
    hooks/
    api/
    types.ts
    index.ts

Layer-based vs Feature-based

// LAYER-BASED: Small apps, simple domains
src/
  components/
  services/
  models/
  utils/

// FEATURE-BASED: Large apps, complex domains
src/
  features/
    users/
    products/
    orders/
  shared/
    components/
    utils/

5. Import/Export Patterns

Barrel Exports (index.ts)

// components/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button';

// Usage: Clean imports
import { Button } from '@/components/Button';

Feature Module API

// features/auth/index.ts - PUBLIC API
export { LoginForm } from './components/LoginForm';
export { useAuth } from './hooks/useAuth';
export type { User, AuthState } from './types';

// Internal components NOT exported

Path Aliases

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@features/*": ["src/features/*"]
    }
  }
}

See references/import-export-patterns.md for complete patterns.

6. Separation of Concerns

Utils vs Helpers vs Services

// UTILS: Pure functions, no side effects
utils/
  formatDate.ts
  validators.ts

// HELPERS: May have side effects
helpers/
  localStorage.ts
  dom.ts

// SERVICES: External interactions, async
services/
  api.ts
  analytics.ts

Decision Framework

1. PROJECT SIZE
   Small (<10 files)     -> Flat structure
   Medium (10-50 files)  -> Simple grouping
   Large (>50 files)     -> Feature-based

2. TEAM SIZE
   Solo/Pair             -> Flexible structure
   Small team (3-5)      -> Consistent conventions
   Large team (>5)       -> Strict boundaries

3. DOMAIN COMPLEXITY
   Simple                -> Layer-based
   Complex               -> Feature-based

4. SCALING EXPECTATIONS
   Stable                -> Current needs only
   Growing               -> Plan for modularity

Refactoring Triggers

Organization Checklist

## Project Setup
- [ ] Clear root structure (src/, tests/, scripts/)
- [ ] Consistent file naming convention
- [ ] Path aliases configured
- [ ] Index files for clean imports

## Module Organization
- [ ] Features grouped by domain
- [ ] Shared code extracted
- [ ] Clear public APIs (index.ts)
- [ ] No circular dependencies

## File Organization
- [ ] Co-located related files
- [ ] Appropriate nesting depth
- [ ] Consistent naming patterns

## Imports
- [ ] Barrel exports for features
- [ ] Path aliases for common paths
- [ ] Absolute imports preferred
- [ ] No deep relative imports

Reference Files

• references/project-layouts.md - Complete layouts by framework
• references/module-patterns.md - Module boundary patterns
• references/naming-conventions.md - Complete naming guide
• references/import-export-patterns.md - Import/export patterns