# {PROJECT_NAME} Project Documentation

> Auto-generated by autonomous-dev on {DATE}
> Customize sections marked with TODO
> For help: /align-project

**Last Updated**: {DATE}
**Version**: {VERSION}
**Status**: {STATUS}

---

## Project Vision

{PROJECT_VISION}

TODO: Describe what this project does and why it exists.

**Example**:
"{ProjectName} enables developers to solve [problem X] by providing [solution Y].
It was created because existing solutions lacked [gap Z]."

**Why this matters**:
This section helps new contributors quickly understand the project's purpose and
maintains focus during development. Keep it to 1-2 paragraphs.

---

## Core Principle

{CORE_PRINCIPLE}

TODO: What makes this project unique? What's the key architectural insight or approach?

**Example**:
"Active Translation, Not Simple Passthrough - While this project acts as an HTTP proxy,
its primary role is intelligent translation and adaptation between incompatible API formats."

**Why this matters**:
The core principle guides architectural decisions and helps developers understand
the project's philosophy. This prevents feature creep and maintains consistency.

---

## Architecture Overview

{ARCHITECTURE_OVERVIEW}

TODO: Provide a high-level description of how the system is structured.

**Example**:
"This project implements a 5-layer translation architecture that converts between
incompatible API formats while preserving streaming, tool calling, and error handling."

### Architecture Pattern: {ARCHITECTURE_PATTERN}

{PATTERN_DESCRIPTION}

TODO: Choose and describe your architecture pattern:
- **Translation Layer**: Format conversion, adapters
- **MVC/MVVM**: Models, views, controllers
- **Microservices**: Independent services
- **Event-Driven**: Pub/sub, message queues
- **Monolithic**: Single unified codebase

**Why this pattern?**
TODO: Explain why this pattern fits your project's needs.

### Key Components

{COMPONENT_LIST}

TODO: List major components with brief descriptions

**Example**:
- **API Router** (`src/routes/`) - HTTP endpoint handlers
- **Service Layer** (`src/services/`) - Business logic
- **Data Access** (`src/db/`) - Database operations
- **Utilities** (`src/utils/`) - Shared helper functions

### Data Flow

{DATA_FLOW_DIAGRAM}

TODO: Describe or diagram how data moves through the system

**For simple projects**, a text description is fine:
```
1. Client sends request to API endpoint
2. Router validates and forwards to service
3. Service processes and queries database
4. Response formatted and returned to client
```

**For complex projects**, an ASCII diagram helps:
```
┌─────────────────────────────────────────────┐
│              Client Input                   │
└────────────────┬────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────┐
│           This System                       │
│  ┌─────────────────────────────────────┐   │
│  │  1. Receive & Validate              │   │
│  └────────────┬────────────────────────┘   │
│               │                             │
│  ┌────────────▼────────────────────────┐   │
│  │  2. Process & Transform             │   │
│  └────────────┬────────────────────────┘   │
│               │                             │
│  ┌────────────▼────────────────────────┐   │
│  │  3. Store or Forward                │   │
│  └────────────┬────────────────────────┘   │
└───────────────┼─────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────┐
│            Output/Storage                   │
└─────────────────────────────────────────────┘
```

---

## Technology Stack

### Core Technologies

{CORE_TECH}

TODO: List primary technologies

**Example**:
- **Language**: TypeScript 5.3
- **Runtime**: Node.js 20.x
- **Framework**: Express 4.18

### Key Dependencies

{KEY_DEPENDENCIES}

TODO: List critical dependencies and their purpose

**Example**:
- **express** - Web framework for HTTP server
- **zod** - Runtime type validation
- **prisma** - Database ORM and migrations
- **pino** - Structured logging

**Why list dependencies?**
Helps developers understand the tech stack and makes security audits easier.
Focus on dependencies that are core to the architecture, not every dev dependency.

### Development Tools

{DEV_TOOLS}

TODO: Document build and quality tools

**Example**:
- **Build**: tsc (TypeScript compiler)
- **Testing**: Jest with ts-jest
- **Linting**: ESLint with TypeScript plugin
- **Formatting**: Prettier
- **Type Checking**: tsc --noEmit

---

## File Organization Standards

### Root Directory Policy

**Maximum**: 8 essential .md files

**Allowed in root**:
- README.md - Project overview and quick start
- CHANGELOG.md - Version history
- LICENSE - License terms
- CONTRIBUTING.md - Contribution guidelines
- CODE_OF_CONDUCT.md - Community standards
- SECURITY.md - Security policy
- CLAUDE.md - Development workflow (if using Claude Code)
- PROJECT.md - This file

**All other .md files** must be in `docs/` subdirectories.

**Why this policy?**
Keeps root directory clean and scannable. Users can quickly find essential info
without sorting through dozens of documentation files.

### Directory Structure

{DIRECTORY_STRUCTURE}

TODO: Document your actual directory structure

**Example**:
```
project-name/
├── src/              # Source code (all .ts/.js files)
│   ├── routes/       # API endpoints
│   ├── services/     # Business logic
│   ├── models/       # Data models
│   └── utils/        # Helper functions
├── tests/            # All tests
│   ├── unit/         # Unit tests (< 1s)
│   ├── integration/  # Integration tests (< 10s)
│   └── uat/          # User acceptance tests (< 60s)
├── docs/             # Documentation
│   ├── guides/       # User guides
│   ├── debugging/    # Debug and troubleshooting
│   ├── development/  # Developer documentation
│   └── architecture/ # Architecture Decision Records (ADRs)
├── scripts/          # Utility scripts
│   ├── debug/        # Debugging tools
│   └── test/         # Testing utilities
├── dist/             # Build output (gitignored)
└── node_modules/     # Dependencies (gitignored)
```

### When Creating New Files

TODO: Provide examples for common file types

#### Shell Scripts (.sh)

❌ **Wrong**:
```
./test-auth.sh
./debug-local.sh
```

✅ **Correct**:
```
./scripts/test/test-auth.sh
./scripts/debug/debug-local.sh
```

**Rule**: All shell scripts go in `scripts/` subdirectories:
- `scripts/debug/` - Debugging and troubleshooting tools
- `scripts/test/` - Testing utilities
- `scripts/build/` - Build and deployment scripts

#### Documentation (.md)

❌ **Wrong** (unless essential):
```
./GUIDE.md
./ARCHITECTURE.md
./RESEARCH.md
```

✅ **Correct**:
```
./docs/guides/user-guide.md
./docs/architecture/system-design.md
./docs/research/api-comparison.md
```

**Rule**: Documentation goes in `docs/` subdirectories:
- `docs/guides/` - User-facing guides
- `docs/debugging/` - Troubleshooting and debug info
- `docs/development/` - Developer documentation
- `docs/architecture/` - Architecture decisions and diagrams
- `docs/reference/` - API reference, technical specs

**Exception**: Only 8 essential .md files allowed in root (see list above).

#### Source Code

❌ **Wrong**:
```
./my-module.ts
./helper.js
```

✅ **Correct**:
```
./src/my-module.ts
./src/utils/helper.js
./tests/unit/my-module.test.ts
```

**Rule**: All source code in `src/`, all tests in `tests/`.

#### Configuration Files

✅ **Root is OK for config**:
```
./package.json
./tsconfig.json
./.env.example
./.gitignore
```

**Why?** Build tools expect config files in root. This is a standard convention.

---

## Development Workflow

### Setup

{SETUP_INSTRUCTIONS}

TODO: Document setup steps

**Example**:
```bash
# Clone repository
git clone https://github.com/user/project.git
cd project

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your values

# Run database migrations
npm run db:migrate

# Start development server
npm run dev
```

### Building

{BUILD_INSTRUCTIONS}

TODO: Document build process

**Example**:
```bash
# Build for production
npm run build

# Output: dist/ directory with compiled JavaScript
```

### Testing

{TEST_INSTRUCTIONS}

TODO: Document testing commands

**Example**:
```bash
# Run all tests
npm test

# Run specific test category
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only

# Run with coverage
npm run test:coverage

# Watch mode (re-run on file changes)
npm run test:watch
```

### Common Tasks

{COMMON_TASKS}

TODO: List frequent developer tasks

**Example**:
- **Start dev server**: `npm run dev`
- **Run linter**: `npm run lint`
- **Format code**: `npm run format`
- **Type check**: `npm run type-check`
- **Database reset**: `npm run db:reset`
- **View logs**: `tail -f logs/app.log`

**Why document common tasks?**
Reduces onboarding friction and creates muscle memory for frequent operations.

---

## Known Issues

> Track critical issues, bugs, and technical debt here.
> Update status as issues are discovered and resolved.

### Template for New Issues

```markdown
### {NUMBER}. {Issue Title} ({STATUS})

**Status**: CRITICAL | HIGH | MEDIUM | LOW | SOLVED
**Discovered**: {Date}
**Affects**: {Which components/features}

**Problem**:
{Clear description of what's broken or wrong}

**Root Cause**:
{Why does this happen? What's the underlying issue?}

**Solution**: {If SOLVED}
{How was it fixed? Link to commit SHA or PR}

**Workaround**: {If not yet solved}
{How can users work around this issue?}

**Related**:
- Issue: #{number}
- PR: #{number}
- Commit: {SHA}
```

### Example Entry

```markdown
### 1. API Rate Limiting Not Working (HIGH)

**Status**: HIGH
**Discovered**: 2024-01-15
**Affects**: All API endpoints

**Problem**:
Rate limiting middleware is installed but not enforcing limits.
Users can make unlimited requests, risking DoS.

**Root Cause**:
Redis connection string in .env uses wrong port (6380 instead of 6379).
Middleware fails silently when Redis is unavailable.

**Workaround**:
Monitor request counts manually. Plan to fix in next sprint.

**Related**:
- Issue: #42
```

TODO: Add known issues as they're discovered. Keep this section updated!

**Why track issues here?**
Prevents knowledge loss when team members leave. Makes onboarding transparent
about current challenges. Helps prioritize technical debt.

---

## Testing Strategy

### Test Categories

{TEST_CATEGORIES}

TODO: Document your testing approach

**Example**:

#### Unit Tests
- **Location**: `tests/unit/`
- **Count**: {COUNT} tests
- **Framework**: Jest
- **Coverage Target**: 80% overall, 90% for critical paths
- **Purpose**: Test individual functions/modules in isolation
- **Speed**: < 1 second total runtime

**When to write unit tests**:
- New functions or classes
- Bug fixes (test first, then fix)
- Complex logic or algorithms

#### Integration Tests
- **Location**: `tests/integration/`
- **Count**: {COUNT} tests
- **Purpose**: Test component interactions (e.g., API + database)
- **Speed**: < 10 seconds total runtime

**When to write integration tests**:
- New API endpoints
- Database schema changes
- Service-to-service communication

#### User Acceptance Tests (UAT)
- **Location**: `tests/uat/` or documented in `tests/manual/`
- **Count**: {COUNT} scenarios
- **Purpose**: Validate complete user workflows
- **Type**: Automated (< 60s) or manual checklist

**When to write UAT**:
- New user-facing features
- Critical user workflows
- Before releases

### Running Tests

{TEST_COMMANDS}

TODO: Document test execution

**Example**:
```bash
# All automated tests
npm test

# Quick validation (unit tests only)
npm run test:unit

# Comprehensive check (all tests + coverage)
npm run test:all

# Manual test procedures
See: tests/manual/README.md
```

### Coverage Requirements

{COVERAGE_REQUIREMENTS}

TODO: Define coverage targets

**Example**:
- **Minimum overall**: 80%
- **Critical paths** (auth, payments): 90%
- **New code** (in PRs): 100%

**How to check coverage**:
```bash
npm run test:coverage
# Opens: coverage/lcov-report/index.html
```

**Why 80%?**
Balances quality with pragmatism. Some code (simple getters, type definitions)
doesn't benefit from tests. Focus on business logic and critical paths.

---

## Documentation Map

### User Documentation

{USER_DOCS}

TODO: Link to user-facing documentation

**Example**:
- [Getting Started](docs/guides/getting-started.md) - New user onboarding
- [API Reference](docs/reference/api.md) - Complete API documentation
- [Troubleshooting](docs/debugging/common-issues.md) - Common problems and solutions

### Development Documentation

{DEV_DOCS}

TODO: Link to developer documentation

**Example**:
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Architecture Overview](docs/architecture/system-design.md) - System design
- [Coding Standards](docs/development/standards.md) - Code style and conventions
- [Database Schema](docs/development/database.md) - Data model documentation

### Debugging Guides

{DEBUG_DOCS}

TODO: Link to debugging resources

**Example**:
- [Debug Mode Setup](docs/debugging/debug-mode.md) - Enable verbose logging
- [Common Errors](docs/debugging/common-errors.md) - Error codes and fixes
- [Performance Profiling](docs/debugging/profiling.md) - Find bottlenecks

### Architecture Documentation

{ARCH_DOCS}

TODO: Link to architecture decision records (ADRs)

**Example**:
- [ADR-001: Choosing TypeScript](docs/architecture/adr-001-typescript.md)
- [ADR-002: Database Selection](docs/architecture/adr-002-postgres.md)
- [System Diagrams](docs/architecture/diagrams/) - Visual architecture

**Why maintain a documentation map?**
Helps developers find information quickly. Documents grow organically; a map
prevents them from becoming a maze.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Code style guidelines
- Pull request process
- Development setup details
- Testing requirements
- Commit message conventions

**Quick contributor checklist**:
1. Fork and clone repository
2. Create feature branch (`git checkout -b feature/my-feature`)
3. Make changes with tests
4. Run `npm run full-check` (lint + test + format)
5. Commit with conventional message (`feat:`, `fix:`, etc.)
6. Push and create PR

---

## Maintenance Notes

### Last Review
TODO: Track when this document was last reviewed

**Last full review**: {DATE}
**Reviewed by**: {NAME}
**Changes made**: {SUMMARY}

**Why track reviews?**
PROJECT.md should evolve with the codebase. Schedule quarterly reviews to ensure
accuracy and relevance.

### Update Triggers

**Update PROJECT.md when**:
- Architecture changes (new pattern, major refactor)
- File organization changes (new directories, moved files)
- Technology stack changes (new framework, language version bump)
- Testing strategy changes (new test category, coverage targets)
- Major feature additions (changes to core principle or data flow)

**Don't update for**:
- Minor bug fixes
- Dependency patches
- Code refactoring within existing structure
- Documentation typos

**How to validate after updates**:
```bash
/align-project
```

---

## Version History

### {VERSION} - {DATE}

**Added**:
- {Feature or section}

**Changed**:
- {Updated section}

**Removed**:
- {Deprecated section}

TODO: Track major PROJECT.md changes here

**Why version the documentation?**
Helps track how the project evolved. Useful for understanding architectural
decisions in historical context.

---

**End of PROJECT.md Template**

**Next Steps After Customizing**:

1. Fill in all TODO sections
2. Replace placeholder values ({PROJECT_NAME}, {VERSION}, etc.)
3. Remove sections that don't apply to your project
4. Add project-specific sections as needed
5. Run `/align-project` to validate
6. Commit to version control

**Remember**: PROJECT.md is a living document. Update it as your project evolves!