# Project Structure

## Overview
This document defines the architectural patterns, directory organization, and code structure conventions for this project. It serves as the single source of truth for structural decisions.

## Organization Philosophy

[Describe your approach: feature-first, layered architecture, domain-driven design, monolithic, microservices, etc.]

Example:
- **Feature-first organization**: Code organized by features/domains rather than technical layers
- **Layered architecture**: Traditional separation of presentation, business logic, and data layers
- **Domain-driven design**: Organized around business domains with bounded contexts

## Directory Structure

### Root Level
**Purpose**: Project configuration, documentation, and entry points

Example:
```
project-root/
├── src/              # Source code
├── tests/            # Test files
├── docs/             # Documentation
├── config/           # Configuration files
└── scripts/          # Build and utility scripts
```

### Source Code Organization
**Purpose**: Application code structure

Example patterns:
```
src/
├── features/         # Feature-based modules (recommended)
│   ├── auth/
│   ├── users/
│   └── products/
├── components/       # Shared UI components
├── services/         # Business logic services
├── utils/            # Utility functions
└── types/            # Type definitions
```

OR

```
src/
├── presentation/     # UI layer
├── application/      # Application logic
├── domain/           # Business domain
└── infrastructure/   # External dependencies
```

## Naming Conventions

### Files and Directories
- **Components**: `PascalCase.tsx` or `kebab-case.tsx`
- **Utilities**: `camelCase.ts` or `kebab-case.ts`
- **Constants**: `UPPER_SNAKE_CASE.ts`
- **Types**: `PascalCase.ts` or `types.ts`

Example:
```
UserProfile.tsx       # React component
userService.ts        # Service file
API_ENDPOINTS.ts      # Constants
User.types.ts         # Type definitions
```

### Code Elements
- **Variables**: camelCase
- **Functions**: camelCase
- **Classes**: PascalCase
- **Constants**: UPPER_SNAKE_CASE
- **Interfaces/Types**: PascalCase

## Import Organization

### Order
1. External dependencies (React, libraries)
2. Internal absolute imports (@/...)
3. Relative imports (./...)

Example:
```typescript
// External
import React from 'react'
import { useState } from 'react'
import axios from 'axios'

// Internal absolute
import { Button } from '@/components/Button'
import { useAuth } from '@/features/auth/hooks'

// Relative
import { LocalComponent } from './LocalComponent'
import type { Props } from './types'
```

### Path Aliases
Define path aliases for clean imports:
- `@/`: Maps to `src/`
- `@components/`: Maps to `src/components/`
- `@features/`: Maps to `src/features/`
- `@utils/`: Maps to `src/utils/`

## Architectural Patterns

### Key Principles
1. **Separation of Concerns**: Clear boundaries between layers
2. **Dependency Direction**: Dependencies flow inward (toward domain)
3. **Single Responsibility**: Each module has one clear purpose
4. **DRY (Don't Repeat Yourself)**: Shared logic in reusable modules

### Common Patterns
- **Repository Pattern**: Data access abstraction
- **Service Layer**: Business logic encapsulation
- **Dependency Injection**: Loose coupling between components
- **Factory Pattern**: Object creation abstraction

## File Size Guidelines

- **Maximum file size**: 300-400 lines
- **Component files**: Ideally under 200 lines
- **If exceeding limits**: Split into multiple files or extract logic

## Code Organization Best Practices

1. **Feature Colocation**: Keep related files together
2. **Index Files**: Use index.ts for clean exports
3. **Shared Code**: Extract to shared/ or common/ directories
4. **Test Files**: Colocate with source files or mirror structure in tests/

## Testing Structure

```
tests/
├── unit/             # Unit tests
├── integration/      # Integration tests
└── e2e/              # End-to-end tests
```

OR colocated:
```
src/features/auth/
├── AuthService.ts
├── AuthService.test.ts
└── AuthService.integration.test.ts
```

## Documentation

- **README.md**: Project overview and setup
- **ARCHITECTURE.md**: Detailed architecture decisions
- **API.md**: API documentation
- **CONTRIBUTING.md**: Contribution guidelines

---

**Note**: This document should be updated when architectural decisions change. Document patterns, not exhaustive file lists. New files following existing patterns shouldn't require updates to this document.

**Last Updated**: [Auto-generated by Steering Agent]