# Dev Playbook — Full Documentation

> The complete Dev Playbook, concatenated for LLM ingestion.
> Compact index: https://devplaybook.tansuasici.com/llms.txt
> Site: https://devplaybook.tansuasici.com
> Repo: https://github.com/tansuasici/dev-playbook

---

# Introduction

> Opinionated engineering playbook for modern software teams.

Source: https://devplaybook.tansuasici.com/docs

<p align="center">
  <img src="https://devplaybook.tansuasici.com/assets/logo.png" alt="Dev Playbook" width="160" />
</p>

<h1 align="center">Dev Playbook</h1>

<p align="center">An opinionated engineering playbook — conventions, architecture decisions, processes, and checklists for modern software teams.</p>

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/tansuasici/dev-playbook/blob/main/LICENSE)
[![Markdown Lint](https://github.com/tansuasici/dev-playbook/actions/workflows/lint.yml/badge.svg)](https://github.com/tansuasici/dev-playbook/actions/workflows/lint.yml)
[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](https://github.com/tansuasici/dev-playbook/blob/main/VERSION)

Personal software development playbook. Defines how I build software — from branching strategy to code conventions.

**Purpose**: Every new project reads this repo first and follows these standards. No reinventing the wheel.

## Table of Contents

- [How to Use](#how-to-use)
- [Structure](#structure)
- [Quick Reference](#quick-reference)
- [Principles](#principles)
- [Contributing](#contributing)
- [License](#license)

## How to Use

### For Claude Code / AI Assistants

Add this to your project's `CLAUDE.md`:

```markdown
## Development Process
Follow the playbook at https://github.com/tansuasici/dev-playbook
Read all files under process/ and conventions/ before starting work.
Apply templates/ when creating issues and PRs.
```

Or at the start of a session:

> "Read the dev-playbook repo first, then work on this project."

### For Yourself

Bookmark this repo. Before starting a new project, run through `checklists/new-project-setup.md`.

---

## Structure

```text
dev-playbook/
  process/                     How work flows
    branching.md               Branch strategy and naming
    commits.md                 Conventional Commits rules
    issues.md                  Issue creation and lifecycle
    pull-requests.md           PR process and review outcomes
    board-workflow.md          Kanban board flow
    ci-cd.md                   CI/CD pipeline standards
    code-review.md             How to review code
    incident-response.md       What to do when production breaks
    dependency-management.md   Adding, updating, removing deps
  conventions/                 How code is written
    dotnet.md                  .NET / C# standards
    nextjs.md                  Next.js / React standards
    python.md                  Python standards
    naming.md                  Naming conventions (all languages)
    api-design.md              REST API design standards
    api-error-format.md        Standard error response format (RFC 7807)
    error-handling.md          Exception handling patterns
    testing.md                 Testing philosophy and practices
    logging.md                 Logging levels, structured logging
    observability.md           Metrics, tracing, alerting, health checks
    performance.md             Response budgets, caching, N+1 prevention
    docker.md                  Dockerfile and Compose best practices
    git-hooks.md               Pre-commit hooks setup
    environment-management.md  Environment config, feature flags, secrets
    documentation.md           README template, API docs, inline comments
    accessibility.md           WCAG 2.1 AA, keyboard nav, screen readers
    i18n.md                    Internationalization and localization
  architecture/                How systems are designed
    decisions.md               Architecture Decision Records (ADR)
    multi-tenancy.md           Multi-tenancy with RLS
    security.md                Security standards and OWASP
    database.md                Schema design, migrations, indexing
  templates/                   Copy-paste templates
    issue-feature.md           Feature request template
    issue-bug.md               Bug report template
    pull-request.md            PR template
    claude-md-starter.md       CLAUDE.md starter for new projects
  checklists/                  Step-by-step checklists
    new-project-setup.md       New project bootstrap
    pre-merge.md               Pre-merge review
    release.md                 Release process
    security-audit.md          Periodic security audit
    onboarding.md              New developer onboarding
  .github/                     GitHub integration
    ISSUE_TEMPLATE/            Native issue templates (bug, feature)
    PULL_REQUEST_TEMPLATE.md   Native PR template
    workflows/lint.yml         Markdown lint + broken link check
  labels.yml                   Standard GitHub label set
  CONTRIBUTING.md              How to contribute
  CODE_OF_CONDUCT.md           Community standards
  CHANGELOG.md                 Version history
  VERSION                      Current version (semver)
  LICENSE                      MIT License
```

## Quick Reference

| I want to...                 | Read this                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Start a new project          | [checklists/new-project-setup.md](/docs/checklists/new-project-setup)                                                    |
| Onboard to a project         | [checklists/onboarding.md](/docs/checklists/onboarding)                                                                  |
| Create a feature branch      | [process/branching.md](/docs/process/branching)                                                                          |
| Write a commit message       | [process/commits.md](/docs/process/commits)                                                                              |
| Open an issue                | [process/issues.md](/docs/process/issues) + [templates/](https://github.com/tansuasici/dev-playbook/tree/main/templates) |
| Open a PR                    | [process/pull-requests.md](/docs/process/pull-requests)                                                                  |
| Review code                  | [process/code-review.md](/docs/process/code-review)                                                                      |
| Set up CI/CD                 | [process/ci-cd.md](/docs/process/ci-cd)                                                                                  |
| Handle a production incident | [process/incident-response.md](/docs/process/incident-response)                                                          |
| Manage dependencies          | [process/dependency-management.md](/docs/process/dependency-management)                                                  |
| Design a REST API            | [conventions/api-design.md](/docs/conventions/api-design)                                                                |
| Handle API errors            | [conventions/api-error-format.md](/docs/conventions/api-error-format)                                                    |
| Handle exceptions            | [conventions/error-handling.md](/docs/conventions/error-handling)                                                        |
| Write .NET code              | [conventions/dotnet.md](/docs/conventions/dotnet)                                                                        |
| Write Next.js code           | [conventions/nextjs.md](/docs/conventions/nextjs)                                                                        |
| Write Python code            | [conventions/python.md](/docs/conventions/python)                                                                        |
| Write tests                  | [conventions/testing.md](/docs/conventions/testing)                                                                      |
| Set up logging               | [conventions/logging.md](/docs/conventions/logging)                                                                      |
| Set up monitoring            | [conventions/observability.md](/docs/conventions/observability)                                                          |
| Optimize performance         | [conventions/performance.md](/docs/conventions/performance)                                                              |
| Write a Dockerfile           | [conventions/docker.md](/docs/conventions/docker)                                                                        |
| Set up git hooks             | [conventions/git-hooks.md](/docs/conventions/git-hooks)                                                                  |
| Manage environments          | [conventions/environment-management.md](/docs/conventions/environment-management)                                        |
| Write documentation          | [conventions/documentation.md](/docs/conventions/documentation)                                                          |
| Make it accessible           | [conventions/accessibility.md](/docs/conventions/accessibility)                                                          |
| Add i18n support             | [conventions/i18n.md](/docs/conventions/i18n)                                                                            |
| Design a database            | [architecture/database.md](/docs/architecture/database)                                                                  |
| Design a multi-tenant system | [architecture/multi-tenancy.md](/docs/architecture/multi-tenancy)                                                        |
| Review before merge          | [checklists/pre-merge.md](/docs/checklists/pre-merge)                                                                    |
| Prepare a release            | [checklists/release.md](/docs/checklists/release)                                                                        |
| Run a security audit         | [checklists/security-audit.md](/docs/checklists/security-audit)                                                          |

## Principles

1. **Every change has an issue** — No ad-hoc work. Track everything.
2. **Every issue has a branch** — Never push directly to main.
3. **Every branch has a PR** — Even solo. PRs are your audit trail.
4. **CI must pass before merge** — No exceptions. Tests are not optional.
5. **Keep commits atomic** — One concern per commit. Easy to bisect, easy to revert.
6. **Simplicity over cleverness** — Make it work, make it right, then make it fast.

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](/docs/contributing) for guidelines.

## License

This project is licensed under the [MIT License](https://github.com/tansuasici/dev-playbook/blob/main/LICENSE).

---

# Contributing

> How to contribute to Dev Playbook.

Source: https://devplaybook.tansuasici.com/docs/contributing

First off, thanks for taking the time to contribute! This playbook is meant to be a living document — improvements, corrections, and new guides are always welcome.

## How to Contribute

### Reporting Issues

- Use the **Bug Report** template for errors, broken links, or incorrect information
- Use the **Feature Request** template for suggesting new guides or improvements
- Check existing issues first to avoid duplicates

### Suggesting Changes

1. **Fork** the repository
2. **Create a branch**: `docs/<short-description>` (e.g., `docs/add-graphql-guide`)
3. **Make your changes** following the style guide below
4. **Submit a PR** with a clear description of what you changed and why

### What We're Looking For

- **New guides** for technologies or practices not yet covered
- **Corrections** to existing content (outdated info, broken examples)
- **Better examples** — real-world, practical code snippets
- **Translations** — making the playbook accessible in other languages
- **Typo fixes** — even small improvements matter

## Style Guide

### File Structure

Every guide follows this pattern:

```markdown
# Title

## Section (with table if applicable)

| Column | Column |
|--------|--------|

### Subsection

- Bullet points for rules
- Code blocks for examples

## Anti-Patterns (if applicable)

What NOT to do, with examples.
```

### Writing Style

- **Be direct** — lead with the rule, then explain why
- **Use tables** for comparisons and reference material
- **Include code examples** in all relevant languages (.NET, TypeScript, Python)
- **Show good AND bad** — `// GOOD` and `// BAD` patterns
- **Keep it practical** — real-world examples over theoretical explanations
- **No fluff** — every sentence should add value

### Code Examples

- Use fenced code blocks with language identifiers
- Include examples for .NET (C#), TypeScript, and Python where applicable
- Keep examples minimal but complete — enough to understand the concept
- Use realistic variable names and scenarios

### Naming Conventions

- **Files**: `kebab-case.md` (e.g., `api-design.md`, `error-handling.md`)
- **Headings**: Title Case for H1, Sentence case for H2+
- **Folders**: lowercase, single word when possible

## Review Process

1. All PRs require at least one review
2. Reviewers check for accuracy, clarity, and consistency with existing guides
3. Discussions are welcome — suggest improvements, ask questions
4. Once approved, maintainer merges with squash

## Code of Conduct

This project follows the [Contributor Covenant Code of Conduct](https://github.com/tansuasici/dev-playbook/blob/main/CODE_OF_CONDUCT.md). By participating, you agree to uphold this code.

## Questions?

Open an issue with the label `question` — happy to help.

---

# Architecture Decision Records

> How we document and track architectural decisions.

Source: https://devplaybook.tansuasici.com/docs/architecture/decisions

## How to Use This File

When making a significant technical decision, document it here. Future-you (and AI assistants) will thank you.

## Format

```markdown
### ADR-NNN: Title

**Date**: YYYY-MM-DD
**Status**: Accepted | Superseded | Deprecated
**Context**: Why did this decision come up?
**Decision**: What did you decide?
**Consequences**: What are the trade-offs?
```

---

### ADR-001: Clean Architecture for Backend

**Date**: Project start
**Status**: Accepted
**Context**: Need a maintainable, testable backend structure that separates concerns.
**Decision**: Use Clean Architecture with 4 layers: Domain → Application → Infrastructure → Api.
**Consequences**:

- (+) Domain logic is framework-independent and highly testable
- (+) Infrastructure can be swapped (e.g., change ORM, change DB)
- (-) More files and indirection for simple CRUD operations
- (-) New developers need to understand the layer boundaries

### ADR-002: CQRS with MediatR

**Date**: Project start
**Status**: Accepted
**Context**: Need clear separation between read and write operations for maintainability.
**Decision**: Use MediatR for command/query dispatch. One handler per use case.
**Consequences**:

- (+) Each use case is isolated and testable
- (+) Easy to add cross-cutting concerns (validation, logging) via behaviors
- (-) Boilerplate: Command + Handler + Validator per operation
- (-) Overkill for simple CRUD, but consistency wins

### ADR-003: Mapster over AutoMapper

**Date**: Project start
**Status**: Accepted
**Context**: Need object mapping between DTOs and entities.
**Decision**: Use Mapster instead of AutoMapper.
**Consequences**:

- (+) No commercial license issues (AutoMapper changed to commercial)
- (+) Better performance (compile-time mapping)
- (+) Similar API, easy to learn
- (-) Smaller community than AutoMapper

---

## Template for New Decisions

Copy this when adding a new ADR:

```markdown
### ADR-NNN: Title

**Date**: YYYY-MM-DD
**Status**: Accepted
**Context**: <Why did this come up?>
**Decision**: <What was decided?>
**Consequences**:
- (+) <Positive outcome>
- (-) <Trade-off or downside>
```

## Categories of Decisions to Document

- Programming language or framework choices
- Database selections (relational, vector, cache, analytics)
- Authentication/authorization approach
- API design (REST, GraphQL, gRPC)
- AI/ML service provider choices
- Hosting and deployment strategy
- Third-party service integrations
- Library choices where multiple options exist

---

# Database Patterns

> Database design conventions and migration strategies.

Source: https://devplaybook.tansuasici.com/docs/architecture/database

## Schema Design

### Naming

| Element            | Convention             | Example                             |
| ------------------ | ---------------------- | ----------------------------------- |
| Tables             | PascalCase, plural     | `Courses`, `EnrollmentRecords`      |
| Columns            | PascalCase             | `CreatedAt`, `TenantId`, `IsActive` |
| Primary keys       | `Id` (Guid or int)     | `Id`                                |
| Foreign keys       | `<Entity>Id`           | `CourseId`, `UserId`                |
| Indexes            | `IX_<Table>_<Columns>` | `IX_Courses_TenantId`               |
| Unique constraints | `UQ_<Table>_<Columns>` | `UQ_Users_Email_TenantId`           |
| FK constraints     | `FK_<Child>_<Parent>`  | `FK_Enrollments_Courses`            |

### Standard Columns

Every table should have these base columns:

```sql
Id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
TenantId    UUID NOT NULL,          -- multi-tenancy (if applicable)
CreatedAt   TIMESTAMPTZ NOT NULL DEFAULT now(),
UpdatedAt   TIMESTAMPTZ NULL,
CreatedBy   UUID NULL,              -- optional: who created it
IsDeleted   BOOLEAN NOT NULL DEFAULT false  -- soft delete (if needed)
```

### Data Types

| Use        | PostgreSQL                  | Avoid                                               |
| ---------- | --------------------------- | --------------------------------------------------- |
| IDs        | `UUID`                      | `SERIAL` (unless performance-critical)              |
| Timestamps | `TIMESTAMPTZ`               | `TIMESTAMP` (no timezone = bugs)                    |
| Money      | `DECIMAL(18,2)`             | `FLOAT`, `REAL` (precision loss)                    |
| Booleans   | `BOOLEAN`                   | `INT` with 0/1                                      |
| Enums      | `SMALLINT` + app-level enum | `VARCHAR` (typo-prone), `PG ENUM` (hard to migrate) |
| Text       | `VARCHAR(N)` with limit     | `TEXT` without limit (unbounded = risk)             |
| JSON       | `JSONB`                     | `JSON` (not indexable)                              |

## Migrations

### Rules

1. **Always use migrations** — Never `EnsureCreated()` or manual DDL in production
2. **Migrations are forward-only** — Never edit a migration after it has been applied
3. **One migration per change** — Don't bundle unrelated schema changes
4. **Test rollback** — Every migration should be reversible (down migration)
5. **Name descriptively** — `AddMaxCapacityToCourses`, not `Update1` or `Migration_003`

### Dangerous Operations

These require extra caution (can cause downtime or data loss):

| Operation                | Risk                    | Safe Alternative                                        |
| ------------------------ | ----------------------- | ------------------------------------------------------- |
| Drop column              | Data loss               | Add `IsDeleted`/rename first, drop later                |
| Rename column            | Breaks running code     | Add new column → copy data → drop old (multi-step)      |
| Add NOT NULL column      | Fails if table has data | Add as nullable → backfill → alter to NOT NULL          |
| Change column type       | Data truncation         | Add new column → migrate data → swap                    |
| Drop table               | Data loss               | Rename to `_deprecated_` first, drop after verification |
| Add index on large table | Locks table             | `CREATE INDEX CONCURRENTLY` (PostgreSQL)                |

### Migration in CI

- Run migrations as part of the deployment pipeline
- Test migrations against a copy of production data (or realistic test data)
- Never run migrations manually in production — always automated

## Indexing

### When to Add an Index

- Columns used in `WHERE` clauses frequently
- Columns used in `JOIN` conditions
- Columns used in `ORDER BY`
- Foreign key columns (PostgreSQL doesn't auto-index FKs)
- `TenantId` — always index this (appears in every query)

### When NOT to Add an Index

- Small tables (\\< 1000 rows) — sequential scan is faster
- Columns with very low cardinality (boolean, status with 3 values)
- Write-heavy tables where read performance isn't critical

### Composite Index Order

Put the most selective column first:

```sql
-- Good: TenantId first (narrows the search), then status
CREATE INDEX IX_Courses_Tenant_Status ON Courses (TenantId, Status);

-- Query benefits from this index:
SELECT * FROM Courses WHERE TenantId = @tid AND Status = 'active';
```

## Query Performance

1. **Use `EXPLAIN ANALYZE`** to verify query plans before deploying
2. **Avoid `SELECT *`** — project only the columns you need
3. **Use pagination** — never return unbounded result sets
4. **Avoid N+1 queries** — use `JOIN`, `Include()`, or batch loading
5. **Use `AsNoTracking()`** for read-only queries in EF Core
6. **Connection pooling** — always use a connection pool (default in EF Core)

## Backups

- **Automated daily backups** with point-in-time recovery
- **Test restore** at least monthly — untested backups are not backups
- **Retain** 7 daily + 4 weekly + 3 monthly backups
- **Store offsite** — backups on the same server as the DB are useless if the server dies

## Seed Data

- Use seed data for development only (test accounts, sample data)
- Never seed production databases with test data
- Store seed scripts in `Infrastructure/Persistence/Seeds/`
- Seed data should be idempotent (safe to run multiple times)

---

# Multi-Tenancy

> Multi-tenant architecture patterns and data isolation.

Source: https://devplaybook.tansuasici.com/docs/architecture/multi-tenancy

## When to Use

Any B2B SaaS where each customer (organization, university, company) needs isolated data.

## Strategy: Row-Level Security (RLS)

Single database, shared schema, `TenantId` column on every table.

### Why RLS over separate databases?

| Approach                       | Pros                                           | Cons                                                               |
| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
| **Separate DB per tenant**     | Full isolation, easy backup/restore per tenant | Expensive, hard to manage migrations, connection pooling nightmare |
| **Separate schema per tenant** | Good isolation, same DB                        | Migration complexity, dynamic schema routing                       |
| **RLS (shared schema)**        | Simple, cost-effective, easy migrations        | Must be rigorous about filtering, noisy neighbor risk              |

For most projects, **RLS is the right default**. Switch to separate DBs only when regulatory requirements demand it.

## Implementation Checklist

### 1. Every Entity Has TenantId

```csharp
public abstract class BaseEntity
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
}
```

**No exceptions.** If an entity doesn't have `TenantId`, it's a bug.

### 2. Tenant Resolution Middleware

Resolve tenant from the request before any data access:

```text
Request → TenantMiddleware → Resolve TenantId → Set in context → Continue
```

Resolution strategies (pick one or combine):

- **Subdomain**: `acme.app.com` → TenantId for Acme
- **Header**: `X-Tenant-Id: <guid>`
- **JWT claim**: `tenant_id` in the access token
- **Path**: `/api/tenants/{id}/...` (less clean)

### 3. Global Query Filter

In EF Core, apply a global filter so every query is automatically scoped:

```csharp
modelBuilder.Entity<Course>()
    .HasQueryFilter(e => e.TenantId == _currentTenant.Id);
```

This is your safety net — even if a developer forgets to filter, the global filter catches it.

### 4. Tenant Scoping in Every Layer

| Layer                 | How                                                                              |
| --------------------- | -------------------------------------------------------------------------------- |
| **API**               | Middleware resolves tenant, sets in scoped service                               |
| **Application**       | Handlers receive tenant from DI, pass to repositories                            |
| **Infrastructure**    | EF global query filter + explicit checks on write                                |
| **External services** | Prefix keys/buckets with tenant (Redis: `tenant:{id}:...`, MinIO: `tenant-{id}`) |

### 5. Cross-Tenant Prevention

- **Never** expose an API that lists data across tenants (except super-admin)
- **Always** validate that the resource belongs to the current tenant on update/delete
- **Audit** cross-tenant access attempts (log as security event)

## External Service Isolation

| Service    | Isolation Strategy                                                 |
| ---------- | ------------------------------------------------------------------ |
| PostgreSQL | Global query filter with TenantId                                  |
| Redis      | Key prefix: `tenant:{tenantId}:cache:...`                          |
| MinIO/S3   | Bucket per tenant: `tenant-{tenantId}`                             |
| Qdrant     | Collection per course (already tenant-scoped via course ownership) |
| ClickHouse | TenantId column in every event table                               |

## Testing Multi-Tenancy

Critical tests to write:

1. **Tenant A cannot see Tenant B's data** — Create data for two tenants, query as each, verify isolation
2. **Missing TenantId fails** — Requests without tenant context should be rejected (401/403)
3. **Write operations validate tenant** — Updating a resource from another tenant should fail
4. **Global filter works** — Raw query returns all data, but EF query returns only current tenant's data

---

# Security Architecture

> Security guidelines, threat modeling, and best practices.

Source: https://devplaybook.tansuasici.com/docs/architecture/security

## Authentication

### JWT Strategy

- **Access token**: Short-lived (15 minutes)
- **Refresh token**: Long-lived (7 days), stored in HttpOnly cookie
- **Never** store tokens in localStorage (XSS vulnerable)
- Include `tenantId` and `role` in token claims

### Password Policy

- Minimum 8 characters
- At least one uppercase, one lowercase, one digit
- Use bcrypt or Argon2 for hashing (never MD5, never SHA without salt)
- Rate limit login attempts (5 attempts per 15 minutes per IP)

## Authorization

- Role-based access control (RBAC) as the baseline
- Validate permissions at the API layer (middleware or attribute-based)
- Never trust client-side role checks alone — always verify server-side
- Tenant isolation is an authorization boundary — crossing it is a security incident

## Input Validation

### API Layer

- Validate ALL input at the boundary (controllers/route handlers)
- Use schema validation (FluentValidation, Zod, Pydantic)
- Reject invalid input early — don't let it reach business logic

### Common Attacks to Prevent

| Attack              | Prevention                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------ |
| **SQL Injection**   | Parameterized queries (EF Core, prepared statements). Never string-concatenate SQL.        |
| **XSS**             | Sanitize user-generated content. Use framework defaults (React auto-escapes). CSP headers. |
| **CSRF**            | Anti-forgery tokens for form submissions. SameSite cookies.                                |
| **File Upload**     | Validate MIME type AND extension. Size limits. Scan for malware. Store outside webroot.    |
| **Mass Assignment** | Use DTOs, never bind directly to entities. Whitelist properties.                           |
| **Path Traversal**  | Never use user input in file paths. Validate and sanitize.                                 |

## API Security

### Headers

```text
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
X-XSS-Protection: 0  (rely on CSP instead)
```

### CORS

- Whitelist only known origins (tenant subdomains)
- Never use `Access-Control-Allow-Origin: *` in production
- Be specific about allowed methods and headers

### Rate Limiting

- Per-tenant and per-user limits
- Stricter limits on auth endpoints
- Return `429 Too Many Requests` with `Retry-After` header

## Secrets Management

- **Never** commit secrets to git (`.env`, API keys, connection strings)
- Use `.env.example` with placeholder values
- Production: environment variables or secrets manager (Azure Key Vault, AWS Secrets Manager)
- Rotate secrets regularly, especially after team member departures

### .gitignore Must Include

```text
.env
.env.local
.env.production
*.pem
*.key
credentials.json
appsettings.Development.json  (if it contains real secrets)
```

## Logging

- **Never log**: passwords, tokens, credit card numbers, personal health info
- **OK to log**: user IDs, request paths, response status codes, latency, error types
- Use structured logging (key-value pairs, not interpolated strings)
- Log security events: failed logins, permission denials, cross-tenant access attempts

## Data Privacy (GDPR/KVKK)

- All personal data must be deletable (right to erasure)
- Document what personal data you collect and why
- Provide data export functionality (right to portability)
- Encrypt personal data at rest
- Data retention policies: define how long you keep data and auto-delete after

## Dependency Security

- Run `npm audit` / `dotnet list package --vulnerable` in CI
- Update dependencies with known vulnerabilities promptly
- Pin versions to avoid supply-chain attacks via version hijacking
- Review new dependencies before adding — prefer well-maintained, widely-used packages

---

# Naming Conventions

> Consistent naming across code, files, and infrastructure.

Source: https://devplaybook.tansuasici.com/docs/conventions/naming

## Universal Rules

1. **English only** — All code, variables, functions, files, commits, branches, PR titles: English
2. **Be descriptive** — `getUserById` not `getUser`, `isEmailVerified` not `flag`
3. **Be consistent** — Pick one term and stick with it. Don't mix `user`/`account`/`member` for the same concept.
4. **No abbreviations** — `repository` not `repo`, `configuration` not `config`. Exception: universally understood ones (`id`, `url`, `api`, `dto`, `db`)

## By Language

| Element        | .NET (C#)     | TypeScript/JS         | Python                |
| -------------- | ------------- | --------------------- | --------------------- |
| Files          | PascalCase.cs | kebab-case.ts         | snake\_case.py        |
| Classes        | PascalCase    | PascalCase            | PascalCase            |
| Interfaces     | IPascalCase   | PascalCase            | PascalCase (Protocol) |
| Functions      | PascalCase    | camelCase             | snake\_case           |
| Variables      | camelCase     | camelCase             | snake\_case           |
| Constants      | PascalCase    | SCREAMING\_SNAKE      | SCREAMING\_SNAKE      |
| Private fields | \_camelCase   | \_camelCase or #field | \_snake\_case         |
| Enums          | PascalCase    | PascalCase            | PascalCase            |

## Git

| Element  | Convention                  | Example                          |
| -------- | --------------------------- | -------------------------------- |
| Branch   | type/kebab-case             | `feat/user-authentication`       |
| Commit   | type: lowercase description | `feat: add user login`           |
| Tag      | semver                      | `v1.0.0`                         |
| PR title | imperative, \\< 70 chars    | `Add course enrollment capacity` |

## Project Structure

| Element       | Convention                 | Example                                            |
| ------------- | -------------------------- | -------------------------------------------------- |
| Directories   | kebab-case                 | `user-management/`                                 |
| Config files  | kebab-case or dot-notation | `.env`, `docker-compose.yml`                       |
| Documentation | kebab-case.md              | `api-reference.md`                                 |
| Test files    | Match source + test suffix | `course-service.test.ts`, `test_course_service.py` |

## Database

| Element      | Convention             | Example                        |
| ------------ | ---------------------- | ------------------------------ |
| Tables       | PascalCase (plural)    | `Courses`, `EnrollmentRecords` |
| Columns      | PascalCase             | `CreatedAt`, `TenantId`        |
| Foreign keys | FK\_Child\_Parent      | `FK_Enrollment_Course`         |
| Indexes      | IX\_Table\_Column      | `IX_Courses_TenantId`          |
| Migrations   | Timestamp\_Description | `20250310_AddCourseTable`      |

## API Endpoints

```text
GET    /api/courses              ← List
GET    /api/courses/{id}         ← Get by ID
POST   /api/courses              ← Create
PUT    /api/courses/{id}         ← Full update
PATCH  /api/courses/{id}         ← Partial update
DELETE /api/courses/{id}         ← Delete

# Nested resources
GET    /api/courses/{id}/students
POST   /api/courses/{id}/enroll
```

- Plural nouns for resources
- kebab-case for multi-word: `/api/course-categories`
- No verbs in URLs (except actions): `/api/courses/{id}/enroll` is OK
- Version prefix if needed: `/api/v1/courses`

## Common Naming Patterns

| Concept      | Pattern                     | Example                            |
| ------------ | --------------------------- | ---------------------------------- |
| Boolean      | is/has/can/should prefix    | `isActive`, `hasPermission`        |
| Collections  | plural                      | `courses`, `studentIds`            |
| Handlers     | verb + noun + Handler       | `CreateCourseHandler`              |
| Services     | noun + Service              | `CourseService`                    |
| Repositories | noun + Repository           | `CourseRepository`                 |
| DTOs         | noun + Dto/Request/Response | `CourseDto`, `CreateCourseRequest` |
| Validators   | noun + Validator            | `CreateCourseValidator`            |
| Middleware   | noun + Middleware           | `TenantMiddleware`                 |

---

# API Design

> RESTful API design principles and standards.

Source: https://devplaybook.tansuasici.com/docs/conventions/api-design

## URL Structure

```text
https://api.example.com/api/{resource}
```

- **Plural nouns** for resources: `/courses`, `/users`, `/enrollments`
- **kebab-case** for multi-word: `/course-categories`, `/audit-logs`
- **No verbs** in URLs — use HTTP methods instead
- **Nesting** for relationships: `/courses/{id}/students`
- **Max 2 levels** of nesting. Beyond that, use query params or top-level resource.

## HTTP Methods

| Method   | Purpose          | Idempotent | Request Body  | Response               |
| -------- | ---------------- | ---------- | ------------- | ---------------------- |
| `GET`    | Read resource(s) | Yes        | No            | 200 + data             |
| `POST`   | Create resource  | No         | Yes           | 201 + created resource |
| `PUT`    | Full update      | Yes        | Yes           | 200 + updated resource |
| `PATCH`  | Partial update   | Yes        | Yes (partial) | 200 + updated resource |
| `DELETE` | Remove resource  | Yes        | No            | 204 (no content)       |

## Response Format

### Success (single resource)

```json
{
  "id": "abc-123",
  "title": "Introduction to Psychology",
  "createdAt": "2025-03-10T14:30:00Z"
}
```

### Success (collection)

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 98
  }
}
```

### Error

See [api-error-format.md](/docs/conventions/api-error-format) for the standard error format.

## Pagination

**Offset-based** (default for most use cases):

```text
GET /api/courses?page=2&pageSize=20
```

| Parameter  | Default | Max | Description           |
| ---------- | ------- | --- | --------------------- |
| `page`     | 1       | —   | Page number (1-based) |
| `pageSize` | 20      | 100 | Items per page        |

Response includes pagination metadata in the response body (see above).

**Cursor-based** (for real-time feeds, infinite scroll):

```text
GET /api/notifications?cursor=eyJpZCI6MTIzfQ&limit=20
```

Use cursor-based when:

- Data changes frequently (new items inserted)
- You need consistent pagination without duplicates
- Large datasets where OFFSET is slow

## Filtering

Use query parameters:

```text
GET /api/courses?status=active&departmentId=5&search=psychology
```

- **Exact match**: `?status=active`
- **Search/partial**: `?search=psych` (searches relevant text fields)
- **Date range**: `?createdAfter=2025-01-01&createdBefore=2025-12-31`
- **Multiple values**: `?status=active,archived` (comma-separated)

## Sorting

```text
GET /api/courses?sortBy=createdAt&sortOrder=desc
```

| Parameter   | Values        | Default     |
| ----------- | ------------- | ----------- |
| `sortBy`    | Field name    | `createdAt` |
| `sortOrder` | `asc`, `desc` | `desc`      |

For multiple sort fields: `?sortBy=status,-createdAt` (prefix `-` for descending).

## Versioning

Prefer **URL path versioning** when breaking changes are needed:

```text
/api/v1/courses
/api/v2/courses
```

Rules:

- Don't version from day one — start with `/api/courses`
- Add versioning only when you make a breaking change
- Support the previous version for a deprecation period
- Document the migration path

## Rate Limiting

Return these headers on every response:

```text
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000
```

When exceeded, return `429 Too Many Requests` with `Retry-After` header.

## Common Patterns

### Bulk Operations

```text
POST /api/courses/bulk-delete
Body: { "ids": ["abc", "def", "ghi"] }
```

### Actions (non-CRUD operations)

```text
POST /api/courses/{id}/publish
POST /api/courses/{id}/archive
POST /api/users/{id}/deactivate
```

### Health Check

```text
GET /api/health          → 200 { "status": "healthy" }
GET /api/health/ready    → 200 or 503 (checks dependencies)
```

## Response Codes Cheat Sheet

| Code                        | When                                               |
| --------------------------- | -------------------------------------------------- |
| `200 OK`                    | Successful GET, PUT, PATCH                         |
| `201 Created`               | Successful POST (include `Location` header)        |
| `204 No Content`            | Successful DELETE                                  |
| `400 Bad Request`           | Validation error, malformed request                |
| `401 Unauthorized`          | Missing or invalid authentication                  |
| `403 Forbidden`             | Authenticated but not authorized                   |
| `404 Not Found`             | Resource doesn't exist                             |
| `409 Conflict`              | Business rule violation (duplicate, capacity full) |
| `422 Unprocessable Entity`  | Valid JSON but semantically wrong                  |
| `429 Too Many Requests`     | Rate limit exceeded                                |
| `500 Internal Server Error` | Unhandled server error (never expose details)      |

---

# API Error Format

> Standardized error response format for APIs.

Source: https://devplaybook.tansuasici.com/docs/conventions/api-error-format

## Standard: RFC 7807 (Problem Details)

Use a consistent error format across all APIs, based on [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807).

## Error Response Shape

```json
{
  "type": "https://docs.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "instance": "/api/courses",
  "traceId": "00-abc123-def456-01",
  "errors": {
    "title": ["Title is required.", "Title must be under 200 characters."],
    "maxCapacity": ["Max capacity must be a positive number."]
  }
}
```

## Field Definitions

| Field      | Required | Description                                                                  |
| ---------- | -------- | ---------------------------------------------------------------------------- |
| `type`     | Yes      | URI identifying the error type (link to docs)                                |
| `title`    | Yes      | Human-readable summary (same for all instances of this type)                 |
| `status`   | Yes      | HTTP status code                                                             |
| `detail`   | Yes      | Human-readable explanation specific to this occurrence                       |
| `instance` | No       | The request path that caused the error                                       |
| `traceId`  | No       | Correlation ID for debugging                                                 |
| `errors`   | No       | Field-level validation errors (key: field name, value: error messages array) |

## Error Types by Status Code

### 400 Bad Request — Validation Error

```json
{
  "type": "https://docs.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "errors": {
    "email": ["Email is required."],
    "password": ["Password must be at least 8 characters."]
  }
}
```

### 401 Unauthorized — Authentication Required

```json
{
  "type": "https://docs.example.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required to access this resource."
}
```

### 403 Forbidden — Insufficient Permissions

```json
{
  "type": "https://docs.example.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to delete this course."
}
```

### 404 Not Found

```json
{
  "type": "https://docs.example.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course with ID 'abc-123' was not found."
}
```

### 409 Conflict — Business Rule Violation

```json
{
  "type": "https://docs.example.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Course has reached maximum enrollment capacity."
}
```

### 429 Too Many Requests

```json
{
  "type": "https://docs.example.com/errors/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

### 500 Internal Server Error

```json
{
  "type": "https://docs.example.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again later."
}
```

**Never expose stack traces, exception messages, or internal details in 500 responses.**

## Implementation

### .NET (ASP.NET Core)

ASP.NET Core has built-in Problem Details support:

```csharp
builder.Services.AddProblemDetails();

// In exception handler middleware
app.UseExceptionHandler(appBuilder =>
{
    appBuilder.Run(async context =>
    {
        var problemDetails = new ProblemDetails
        {
            Status = 500,
            Title = "Internal Server Error",
            Detail = "An unexpected error occurred."
        };
        context.Response.StatusCode = 500;
        await context.Response.WriteAsJsonAsync(problemDetails);
    });
});
```

### Next.js (API Routes)

```typescript
function createErrorResponse(status: number, title: string, detail: string, errors?: Record<string, string[]>) {
  return Response.json({
    type: `https://docs.example.com/errors/${title.toLowerCase().replace(/\s/g, '-')}`,
    title,
    status,
    detail,
    ...(errors && { errors }),
  }, { status });
}
```

## Rules

1. **Always return JSON** — Even for errors. No HTML error pages from APIs.
2. **Always include `status`** — Even though it's in the HTTP status code.
3. **Keep `detail` user-friendly** — No stack traces, no internal class names.
4. **Use `errors` object for validation** — One key per field, array of messages per key.
5. **Consistent across all endpoints** — Same shape everywhere. No surprises.
6. **Log the real error server-side** — The client gets a safe message; the server logs the full exception.

---

# Error Handling

> Exception handling patterns and error management strategies.

Source: https://devplaybook.tansuasici.com/docs/conventions/error-handling

> See also: [api-error-format.md](/docs/conventions/api-error-format) for the standard API error response format (RFC 7807).

## Core Principle

**Handle errors at the right level.** Don't catch exceptions you can't meaningfully handle. Let them bubble up to a global handler.

## Error Categories

| Category             | Example                      | Response Code | Handling                               |
| -------------------- | ---------------------------- | ------------- | -------------------------------------- |
| **Validation**       | Invalid email, missing field | 400           | Return specific field errors           |
| **Authentication**   | Missing/expired token        | 401           | Return generic "unauthorized"          |
| **Authorization**    | Wrong role, wrong tenant     | 403           | Return generic "forbidden"             |
| **Not Found**        | Resource doesn't exist       | 404           | Return "not found"                     |
| **Business Rule**    | Course full, duplicate title | 409 / 422     | Return specific business error         |
| **External Service** | API timeout, service down    | 502 / 503     | Retry or degrade gracefully            |
| **Internal**         | Unhandled exception, bug     | 500           | Log full details, return generic error |

## Architecture

```text
Controller / Route Handler
  ↓ catches validation errors → 400
  ↓
Service / Use Case
  ↓ throws business exceptions → 409/422
  ↓
Repository / External Call
  ↓ throws infrastructure exceptions → 502/503
  ↓
Global Exception Handler
  ↓ catches everything else → 500 (logged, generic response)
```

## Implementation

### .NET — Exception Middleware

```csharp
// Custom exception types
public class NotFoundException : Exception
{
    public NotFoundException(string entity, object id)
        : base($"{entity} with id '{id}' was not found.") { }
}

public class BusinessRuleException : Exception
{
    public BusinessRuleException(string message) : base(message) { }
}

public class ConflictException : Exception
{
    public ConflictException(string message) : base(message) { }
}

// Global exception handler middleware
public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (NotFoundException ex)
        {
            context.Response.StatusCode = 404;
            await WriteProblemDetails(context, "Not Found", ex.Message, 404);
        }
        catch (BusinessRuleException ex)
        {
            context.Response.StatusCode = 422;
            await WriteProblemDetails(context, "Business Rule Violation", ex.Message, 422);
        }
        catch (ConflictException ex)
        {
            context.Response.StatusCode = 409;
            await WriteProblemDetails(context, "Conflict", ex.Message, 409);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unhandled exception for {RequestPath}", context.Request.Path);
            context.Response.StatusCode = 500;
            await WriteProblemDetails(context, "Internal Server Error",
                "An unexpected error occurred.", 500);
        }
    }
}
```

### TypeScript — Error Classes

```typescript
// Custom error classes
class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
  ) {
    super(message);
  }
}

class NotFoundError extends AppError {
  constructor(entity: string, id: string) {
    super(404, 'NOT_FOUND', `${entity} with id '${id}' not found`);
  }
}

class BusinessRuleError extends AppError {
  constructor(message: string) {
    super(422, 'BUSINESS_RULE_VIOLATION', message);
  }
}

class ConflictError extends AppError {
  constructor(message: string) {
    super(409, 'CONFLICT', message);
  }
}

// Global error handler (Express / Next.js API route wrapper)
function withErrorHandler(handler: Function) {
  return async (req: Request, res: Response) => {
    try {
      await handler(req, res);
    } catch (error) {
      if (error instanceof AppError) {
        res.status(error.statusCode).json({
          type: `https://docs.api.com/errors/${error.code.toLowerCase()}`,
          title: error.code,
          status: error.statusCode,
          detail: error.message,
        });
      } else {
        logger.error('Unhandled error', { error, path: req.url });
        res.status(500).json({
          type: 'https://docs.api.com/errors/internal',
          title: 'Internal Server Error',
          status: 500,
          detail: 'An unexpected error occurred.',
        });
      }
    }
  };
}
```

### Python — Exception Handlers

```python
# Custom exceptions
class AppException(Exception):
    def __init__(self, status_code: int, code: str, detail: str):
        self.status_code = status_code
        self.code = code
        self.detail = detail

class NotFoundException(AppException):
    def __init__(self, entity: str, id: str):
        super().__init__(404, "NOT_FOUND", f"{entity} with id '{id}' not found")

class BusinessRuleException(AppException):
    def __init__(self, detail: str):
        super().__init__(422, "BUSINESS_RULE_VIOLATION", detail)

# FastAPI exception handler
@app.exception_handler(AppException)
async def app_exception_handler(request: Request, exc: AppException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "type": f"https://docs.api.com/errors/{exc.code.lower()}",
            "title": exc.code,
            "status": exc.status_code,
            "detail": exc.detail,
        },
    )
```

## External Service Errors

### Retry Strategy

```text
Retry 1 → wait 1s
Retry 2 → wait 2s
Retry 3 → wait 4s
Give up → return 503 or fallback
```

```csharp
// .NET — Polly retry policy
builder.Services.AddHttpClient("ExternalApi")
    .AddTransientHttpErrorPolicy(policy =>
        policy.WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt))));
```

### Circuit Breaker

When an external service is consistently failing, stop calling it temporarily:

```text
Closed (normal) → Too many failures → Open (reject calls for 30s) → Half-Open (try one) → Closed
```

### Graceful Degradation

- If the recommendation service is down, show default content instead of an error
- If the email service is down, queue the email for later delivery
- If the search service is down, fall back to database query

## Rules

1. **Never swallow exceptions silently** — catch only if you handle it meaningfully
2. **Never expose internal details** in API responses — stack traces, SQL queries, file paths
3. **Log at the boundary** — global handler logs unhandled exceptions, not every catch block
4. **Use typed exceptions** — `NotFoundException`, not `throw new Exception("not found")`
5. **Fail fast on startup** — missing config, unreachable database = crash, don't limp along
6. **Return consistent error format** — always RFC 7807 Problem Details (see [api-error-format.md](/docs/conventions/api-error-format))
7. **Don't use exceptions for flow control** — check `if (course == null)` instead of catching `NullReferenceException`

## Anti-Patterns

```csharp
// DON'T: Pokemon exception handling (catch 'em all)
try { ... }
catch (Exception) { return null; }  // What went wrong? Nobody knows.

// DON'T: Log and throw (duplicate logging)
catch (Exception ex)
{
    _logger.LogError(ex, "Failed");
    throw;  // Global handler will log AGAIN
}

// DON'T: Expose internals
catch (NpgsqlException ex)
{
    return BadRequest(ex.Message);  // Leaks DB schema info
}

// DON'T: Empty catch
catch (Exception) { }  // Silently swallowed. Debugging nightmare.

// DO: Handle specifically or let it bubble
catch (DuplicateKeyException)
{
    throw new ConflictException("A course with this title already exists");
}
```

---

# Logging

> Structured logging standards and best practices.

Source: https://devplaybook.tansuasici.com/docs/conventions/logging

## Log Levels

| Level             | When to Use                       | Example                                                        |
| ----------------- | --------------------------------- | -------------------------------------------------------------- |
| **Fatal**         | Application cannot continue       | DB connection permanently lost, corrupt config                 |
| **Error**         | Operation failed, needs attention | Unhandled exception, external service down                     |
| **Warning**       | Something unexpected but handled  | Retry succeeded, deprecated API called, rate limit approaching |
| **Information**   | Normal business events            | User logged in, course created, payment processed              |
| **Debug**         | Diagnostic detail for development | Request/response payloads, cache hit/miss, query timing        |
| **Verbose/Trace** | Extremely detailed, noisy         | Method entry/exit, variable values (dev only)                  |

### Production Minimum Level: `Information`

Debug and Verbose should never be enabled in production by default. Use dynamic log level switching for temporary debugging.

## Structured Logging

**Always use structured logging** — key-value pairs, not string interpolation.

```csharp
// GOOD — structured, searchable
_logger.LogInformation("Course created {CourseId} by {UserId} in tenant {TenantId}",
    courseId, userId, tenantId);

// BAD — string interpolation, not searchable
_logger.LogInformation($"Course created {courseId} by {userId}");
```

```typescript
// GOOD
logger.info('Course created', { courseId, userId, tenantId });

// BAD
logger.info(`Course created ${courseId} by ${userId}`);
```

```python
# GOOD
logger.info("Course created", extra={"course_id": course_id, "user_id": user_id})

# BAD
logger.info(f"Course created {course_id} by {user_id}")
```

## What to Log

### Always Log

- **Authentication events**: login success/failure, token refresh, logout
- **Authorization failures**: forbidden access attempts
- **Business events**: resource created/updated/deleted, state transitions
- **External service calls**: request sent, response received, errors (with latency)
- **Background job lifecycle**: started, completed, failed
- **Application startup/shutdown**: config loaded, services registered, graceful shutdown

### Never Log

- Passwords or password hashes
- Access tokens, refresh tokens, API keys
- Credit card numbers or financial details
- Personal health information
- Full request/response bodies in production (use Debug level only)
- Personal data beyond what's needed (email OK for auth events, not for every log)

### Log with Caution

- Email addresses — OK in auth context, mask elsewhere
- User IDs — OK, they're not PII by themselves
- IP addresses — may be PII under GDPR, log only for security events
- Request bodies — Debug level only, redact sensitive fields

## Context Fields

Include these fields consistently in every log entry:

| Field           | Purpose                  | Example           |
| --------------- | ------------------------ | ----------------- |
| `TenantId`      | Multi-tenant isolation   | `"tenant-abc123"` |
| `UserId`        | Who triggered the action | `"user-456"`      |
| `CorrelationId` | Trace across services    | `"req-789xyz"`    |
| `RequestPath`   | Which endpoint           | `"/api/courses"`  |
| `Duration`      | How long it took         | `145` (ms)        |

Use middleware or logging enrichers to add these automatically — don't manually pass them everywhere.

## Log Aggregation

- **Development**: Console output (readable, colored)
- **Staging/Production**: Centralized log aggregation (Seq, ELK, Grafana Loki)
- **Retention**: 30 days for Info+, 7 days for Debug (if enabled)
- **Alerts**: Set up alerts for Error and Fatal level spikes

## Anti-Patterns

```csharp
// DON'T: Log and throw — produces duplicate noise
try { ... }
catch (Exception ex)
{
    _logger.LogError(ex, "Something failed");
    throw; // The global handler will log this AGAIN
}

// DO: Log at the boundary (global exception handler) or at the catch, not both.

// DON'T: Empty catch with log
catch (Exception ex)
{
    _logger.LogError(ex, "Error occurred");
    // and then what? Swallowed silently.
}

// DON'T: Log every method entry/exit in production
_logger.LogInformation("Entering GetCourseById");  // Noise
_logger.LogInformation("Exiting GetCourseById");   // Noise

// DO: Log meaningful events with context
_logger.LogInformation("Course retrieved {CourseId} in {Duration}ms", courseId, elapsed);
```

---

# Observability

> Metrics, tracing, alerting, and health check standards.

Source: https://devplaybook.tansuasici.com/docs/conventions/observability

Logging alone is not enough. A production system needs **metrics**, **tracing**, and **alerting** to be truly observable.

> See also: [logging.md](/docs/conventions/logging) for structured logging standards.

## Three Pillars

| Pillar      | What It Tells You                                 | Tools                         |
| ----------- | ------------------------------------------------- | ----------------------------- |
| **Logs**    | What happened (discrete events)                   | Seq, ELK, Grafana Loki        |
| **Metrics** | How the system is performing (aggregated numbers) | Prometheus, Grafana, InfluxDB |
| **Traces**  | How a request flows across services (distributed) | Jaeger, Zipkin, OpenTelemetry |

## Health Checks

Every service must expose health endpoints.

### Endpoints

```text
GET /api/health          → 200 { "status": "healthy" }
GET /api/health/ready    → 200 or 503 (checks dependencies)
GET /api/health/live     → 200 (process is running, used by k8s liveness probe)
```

### What Readiness Checks

| Dependency    | Check                                 |
| ------------- | ------------------------------------- |
| Database      | Can connect and run a simple query    |
| Redis/Cache   | Can connect and ping                  |
| External API  | Can reach the endpoint (with timeout) |
| Message Queue | Can connect to broker                 |
| File Storage  | Can list/read from bucket             |

```csharp
// .NET
builder.Services.AddHealthChecks()
    .AddNpgSql(connectionString, name: "postgres")
    .AddRedis(redisConnection, name: "redis")
    .AddUrlGroup(new Uri("https://external-api/health"), name: "external-api");
```

```typescript
// Next.js / Express
app.get('/api/health/ready', async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    redis: await checkRedis(),
    storage: await checkStorage(),
  };

  const healthy = Object.values(checks).every(Boolean);
  res.status(healthy ? 200 : 503).json({ status: healthy ? 'healthy' : 'unhealthy', checks });
});
```

## Metrics

### What to Measure

| Metric                 | Type      | Example                                      |
| ---------------------- | --------- | -------------------------------------------- |
| **Request rate**       | Counter   | `http_requests_total`                        |
| **Request duration**   | Histogram | `http_request_duration_seconds`              |
| **Error rate**         | Counter   | `http_errors_total` (by status code)         |
| **Active connections** | Gauge     | `http_active_connections`                    |
| **Queue depth**        | Gauge     | `job_queue_size`                             |
| **Business metrics**   | Counter   | `enrollments_total`, `courses_created_total` |

### RED Method (for services)

Every service should track:

- **R**ate — requests per second
- **E**rrors — failed requests per second
- **D**uration — time per request (p50, p95, p99)

### USE Method (for resources)

Every resource (CPU, memory, disk, connections) should track:

- **U**tilization — percentage in use
- **S**aturation — queue depth / backlog
- **E**rrors — error count

### Naming Convention

```text
<namespace>_<name>_<unit>

# Examples
http_request_duration_seconds
db_query_duration_seconds
cache_hits_total
job_processing_errors_total
```

## Distributed Tracing

### When You Need It

- Multiple services handle a single request
- You need to find where latency comes from
- You need to debug cross-service failures

### Implementation

Use **OpenTelemetry** as the standard — it's vendor-neutral and supports all major backends.

```csharp
// .NET
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddEntityFrameworkCoreInstrumentation()
        .AddOtlpExporter());
```

```python
# Python
from opentelemetry import trace
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

FastAPIInstrumentor.instrument_app(app)
```

### Propagation

- Pass `traceparent` header between services (W3C Trace Context standard)
- Include `CorrelationId` in all log entries for manual correlation
- Never create custom trace ID formats — use the standard

## Alerting

### Alert Rules

| Severity     | Condition                                           | Action                                     |
| ------------ | --------------------------------------------------- | ------------------------------------------ |
| **Critical** | Service down, error rate \\> 50%, data loss risk    | Page on-call immediately                   |
| **Warning**  | Error rate \\> 5%, latency p99 \\> 2s, disk \\> 80% | Notify in Slack, investigate within 1 hour |
| **Info**     | Deployment completed, cert expiring in 30 days      | Log for awareness                          |

### Alert Best Practices

- **Alert on symptoms, not causes** — "API latency \\> 2s" not "CPU \\> 80%"
- **Include runbook links** in alert messages
- **Set appropriate thresholds** — avoid alert fatigue from noisy alerts
- **Use alert grouping** — don't fire 100 alerts for the same incident
- **Test alerts** — regularly verify they fire when expected

### Alert Template

```yaml
alert: HighErrorRate
expr: rate(http_errors_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
for: 5m
labels:
  severity: warning
annotations:
  summary: "High error rate on {{ $labels.service }}"
  description: "Error rate is {{ $value | humanizePercentage }} over the last 5 minutes"
  runbook: "https://wiki.internal/runbooks/high-error-rate"
```

## Dashboards

### Every Service Dashboard Should Have

1. **Request rate** — traffic over time
2. **Error rate** — 4xx and 5xx separately
3. **Latency** — p50, p95, p99 over time
4. **Saturation** — CPU, memory, connections, queue depth
5. **Business metrics** — relevant domain-specific counters

### Dashboard Rules

- One dashboard per service, not one giant dashboard
- Use consistent time ranges and refresh intervals
- Include links to related dashboards and runbooks
- Mark deployment events on graphs for correlation

## Anti-Patterns

- **Logging as the only observability** — Logs alone can't show trends or distributions
- **No health checks** — You can't know if a service is healthy without asking it
- **Alerting on every metric** — Alert fatigue leads to ignored alerts
- **Custom metrics libraries** — Use OpenTelemetry, don't reinvent the wheel
- **Dashboard without context** — Every graph should have a title that explains what "bad" looks like

---

# Testing

> Testing strategies, coverage goals, and test patterns.

Source: https://devplaybook.tansuasici.com/docs/conventions/testing

## Core Principle

**Test behavior, not implementation.** Tests should verify what the code does, not how it does it. If you refactor internals and tests break, the tests were wrong.

## Test Pyramid

```text
        /  E2E  \          ← Few: critical user flows only
       /  Integr. \        ← Some: API endpoints, DB queries, external services
      /    Unit     \      ← Many: business logic, pure functions, handlers
```

| Level           | What to Test                                                   | Tools                       | Speed                  |
| --------------- | -------------------------------------------------------------- | --------------------------- | ---------------------- |
| **Unit**        | Business logic, handlers, services, validators, pure functions | xUnit/Vitest/pytest + mocks | Fast (ms)              |
| **Integration** | API endpoints, DB operations, external service calls           | TestContainers, httpx       | Medium (seconds)       |
| **E2E**         | Critical user flows through the UI                             | Playwright                  | Slow (seconds-minutes) |

## What to Test

### Always Test

- Business logic and domain rules
- Validation logic (valid and invalid inputs)
- Edge cases (null, empty, boundary values, max limits)
- Error handling paths
- Authorization rules (can this role do this?)
- Data transformations (mapping, serialization)

### Don't Bother Testing

- Framework boilerplate (DI registration, middleware wiring)
- Simple CRUD with no business logic
- Third-party library internals
- Private methods directly (test them through public API)
- Getters/setters with no logic

## Test Naming

**Pattern**: `MethodName_Scenario_ExpectedResult`

```csharp
// C#
CreateCourse_WithValidData_ReturnsCourseId()
CreateCourse_WithDuplicateTitle_ThrowsConflictException()
EnrollStudent_WhenCourseIsFull_Returns409()
```

```typescript
// TypeScript
describe('CourseService', () => {
  it('creates a course with valid data', () => {})
  it('throws when course title is duplicate', () => {})
  it('returns 409 when course is at capacity', () => {})
})
```

```python
# Python
def test_create_course_with_valid_data_returns_course_id():
def test_create_course_with_duplicate_title_raises_conflict():
def test_enroll_student_when_full_returns_409():
```

## Test Structure: Arrange-Act-Assert

Every test follows this pattern:

```csharp
[Fact]
public async Task EnrollStudent_WhenCourseIsFull_Returns409()
{
    // Arrange — set up the scenario
    var course = CreateCourse(maxCapacity: 1);
    await EnrollStudent(course.Id, studentId: "first-student");

    // Act — execute the thing being tested
    var result = await _handler.Handle(new EnrollStudentCommand(course.Id, "second-student"));

    // Assert — verify the outcome
    result.StatusCode.Should().Be(409);
}
```

Keep each section short. If Arrange is 20 lines, extract a helper or use a builder/factory.

## Mocking Rules

1. **Mock at boundaries** — external services, databases, file system, clock
2. **Don't mock what you own** — if you wrote the class, use the real thing (or an in-memory fake)
3. **Don't mock value objects** — just construct them
4. **One mock per test** (ideally) — if you need 5 mocks, the code has too many dependencies
5. **Integration tests use real infra** — TestContainers for DB, real Redis, etc.

## Test Data

- **Use builders or factories** for complex objects, not raw constructors everywhere
- **Don't share mutable state** between tests — each test sets up its own data
- **Use meaningful test data** — `"john@example.com"` not `"test123"`
- **Avoid magic numbers** — use named constants or clearly labeled variables

## Coverage

- **Don't chase 100%** — diminishing returns after \~80%
- **Cover the critical paths**: auth, payments, data mutations, business rules
- **Uncovered code is a signal**, not a crime — investigate, don't blindly add tests
- **CI should report coverage** but not block on a threshold (quality \\> quantity)

## When to Write Tests

- **Before fixing a bug**: Write a failing test that reproduces the bug, then fix it
- **During feature development**: Write tests as you implement, not after
- **Not retroactively for old code**: Unless you're modifying it — then add tests for what you touch

## Flaky Tests

Flaky tests (pass sometimes, fail sometimes) are worse than no tests:

- **Fix immediately** or delete — don't leave them failing intermittently
- Common causes: timing issues, shared state, network dependencies, date/time
- Never use `continue-on-error` or `|| true` as a "fix" for flaky tests

---

# Performance

> Response time budgets, caching, and optimization patterns.

Source: https://devplaybook.tansuasici.com/docs/conventions/performance

## Response Time Budgets

| Endpoint Type           | Target (p95) | Max (p99)          |
| ----------------------- | ------------ | ------------------ |
| Simple read (GET by ID) | \\< 100ms    | \\< 200ms          |
| List with pagination    | \\< 200ms    | \\< 500ms          |
| Search with filters     | \\< 300ms    | \\< 800ms          |
| Write (POST/PUT/PATCH)  | \\< 200ms    | \\< 500ms          |
| File upload             | \\< 2s       | \\< 5s             |
| Report generation       | \\< 5s       | \\< 10s (or async) |

If an operation exceeds 10 seconds, make it **asynchronous** — return `202 Accepted` and process in the background.

## Database Performance

### N+1 Query Prevention

The most common performance bug. Loading a list then querying each item individually.

```csharp
// BAD — N+1: 1 query for courses + N queries for instructors
var courses = await _context.Courses.ToListAsync();
foreach (var course in courses)
{
    course.Instructor = await _context.Users.FindAsync(course.InstructorId);
}

// GOOD — eager loading: 1 query with JOIN
var courses = await _context.Courses
    .Include(c => c.Instructor)
    .ToListAsync();
```

```typescript
// BAD — N+1
const courses = await prisma.course.findMany();
for (const course of courses) {
  course.instructor = await prisma.user.findUnique({ where: { id: course.instructorId } });
}

// GOOD — include relation
const courses = await prisma.course.findMany({
  include: { instructor: true },
});
```

```python
# BAD — N+1
courses = session.query(Course).all()
for course in courses:
    print(course.instructor.name)  # lazy load triggers N queries

# GOOD — eager load
courses = session.query(Course).options(joinedload(Course.instructor)).all()
```

### Query Rules

- **Always paginate** list endpoints — never return unbounded results
- **Select only needed columns** — don't `SELECT *` when you need 3 fields
- **Index WHERE, JOIN, ORDER BY columns** — see [database.md](/docs/architecture/database)
- **Use EXPLAIN ANALYZE** on slow queries to understand the execution plan
- **Set query timeouts** — a runaway query shouldn't take down the database

```csharp
// Select only what you need
var courseSummaries = await _context.Courses
    .Where(c => c.TenantId == tenantId && !c.IsDeleted)
    .Select(c => new CourseSummaryDto
    {
        Id = c.Id,
        Title = c.Title,
        StudentCount = c.Enrollments.Count,
    })
    .ToListAsync();
```

## Caching Strategy

### Cache Layers

| Layer           | What to Cache                       | TTL                     | Invalidation                 |
| --------------- | ----------------------------------- | ----------------------- | ---------------------------- |
| **Browser**     | Static assets (JS, CSS, images)     | Long (1 year with hash) | New deployment               |
| **CDN**         | Public pages, images, API responses | Minutes to hours        | Purge on update              |
| **Application** | DB query results, computed values   | Seconds to minutes      | Write-through or event-based |
| **Database**    | Query plans, prepared statements    | Automatic               | Database manages this        |

### When to Cache

- Data that's read far more than written (course catalog, user profiles)
- Expensive computations (analytics, aggregations, reports)
- External API responses (with appropriate TTL)

### When NOT to Cache

- User-specific sensitive data (unless per-user cache with auth)
- Rapidly changing data (real-time feeds, live counters)
- Data that must be consistent (financial transactions, enrollment counts during registration)

### Implementation

```csharp
// .NET — IDistributedCache with Redis
public async Task<CourseDto?> GetCourseAsync(Guid courseId)
{
    var cacheKey = $"course:{courseId}";
    var cached = await _cache.GetStringAsync(cacheKey);

    if (cached != null)
        return JsonSerializer.Deserialize<CourseDto>(cached);

    var course = await _repository.GetByIdAsync(courseId);
    if (course == null) return null;

    var dto = course.ToDto();
    await _cache.SetStringAsync(cacheKey, JsonSerializer.Serialize(dto),
        new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5) });

    return dto;
}

// Invalidate on write
public async Task UpdateCourseAsync(Guid courseId, UpdateCourseRequest request)
{
    await _repository.UpdateAsync(courseId, request);
    await _cache.RemoveAsync($"course:{courseId}");
}
```

```typescript
// TypeScript — Redis cache helper
async function cached<T>(key: string, ttlSeconds: number, fn: () => Promise<T>): Promise<T> {
  const hit = await redis.get(key);
  if (hit) return JSON.parse(hit);

  const result = await fn();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

// Usage
const course = await cached(`course:${id}`, 300, () => db.course.findUnique({ where: { id } }));
```

### Cache Key Convention

```text
<entity>:<id>                    → course:abc-123
<entity>:list:<tenant>:<hash>    → course:list:tenant-1:page1-size20
<entity>:count:<tenant>          → course:count:tenant-1
```

## Frontend Performance

### Core Web Vitals Targets

| Metric                              | Target    | What It Measures    |
| ----------------------------------- | --------- | ------------------- |
| **LCP** (Largest Contentful Paint)  | \\< 2.5s  | Loading performance |
| **INP** (Interaction to Next Paint) | \\< 200ms | Interactivity       |
| **CLS** (Cumulative Layout Shift)   | \\< 0.1   | Visual stability    |

### Rules

- **Lazy load** below-the-fold content and routes
- **Optimize images** — use WebP/AVIF, serve responsive sizes, always set width/height
- **Minimize JavaScript** — code split by route, tree-shake unused imports
- **Prefetch** likely navigation targets
- **Use SSR/SSG** for content pages, CSR for interactive dashboards

```typescript
// Next.js — Dynamic import for heavy components
import dynamic from 'next/dynamic';

const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false,
});

// Image optimization
import Image from 'next/image';

<Image
  src="/hero.jpg"
  alt="Course hero image"
  width={1200}
  height={630}
  priority  // LCP image — load immediately
/>
```

## Background Jobs

Move heavy operations out of the request path:

| Operation             | Approach                                        |
| --------------------- | ----------------------------------------------- |
| Sending emails        | Queue → Background worker                       |
| Generating reports    | Queue → Return job ID → Poll/webhook for result |
| Processing uploads    | Queue → Worker → Notify on completion           |
| Analytics aggregation | Scheduled job (cron)                            |
| Cache warming         | Scheduled job or event-driven                   |

```csharp
// .NET — Return 202 and process in background
[HttpPost("reports/generate")]
public async Task<IActionResult> GenerateReport([FromBody] ReportRequest request)
{
    var jobId = await _backgroundJobs.EnqueueAsync<ReportGenerator>(
        x => x.GenerateAsync(request));

    return Accepted(new { jobId, statusUrl = $"/api/reports/jobs/{jobId}" });
}
```

## Anti-Patterns

- **No pagination** — Returning 10,000 rows because "it works in dev"
- \*\*SELECT \*\*\* — Fetching 20 columns when you need 3
- **Cache everything** — Caching data that changes every second or is accessed once
- **Premature optimization** — Profile first, optimize the bottleneck, not what you guess
- **Synchronous heavy operations** — Generating PDFs or sending emails in the request handler
- **No query monitoring** — You can't fix what you can't see. Log slow queries (\\> 100ms)

---

# .NET Conventions

> C# and .NET specific coding standards.

Source: https://devplaybook.tansuasici.com/docs/conventions/dotnet

## Architecture: Clean Architecture

```text
Solution/
├── src/
│   ├── Domain/           ← Entities, value objects, enums, domain events
│   ├── Application/      ← Use cases, CQRS handlers, DTOs, interfaces
│   ├── Infrastructure/   ← EF Core, external services, repositories
│   └── Api/              ← Controllers, middleware, DI configuration
└── tests/
    ├── UnitTests/
    └── IntegrationTests/
```

**Dependency rule**: Inner layers never reference outer layers. Domain has zero dependencies.

## Patterns

| Pattern         | Tool                                  | Notes                               |
| --------------- | ------------------------------------- | ----------------------------------- |
| CQRS            | MediatR                               | Separate Commands and Queries       |
| Validation      | FluentValidation                      | On every request DTO                |
| Object Mapping  | Mapster                               | NOT AutoMapper (commercial license) |
| ORM             | EF Core                               | Repository pattern on top           |
| Logging         | Serilog                               | Structured logging to Seq           |
| Background Jobs | Hangfire                              | For long-running tasks              |
| Health Checks   | AspNetCore.HealthChecks               | For every external dependency       |
| OpenAPI         | Microsoft.AspNetCore.OpenApi + Scalar | NOT Swashbuckle (deprecated)        |

## Naming

| Element        | Convention       | Example                |
| -------------- | ---------------- | ---------------------- |
| Public members | PascalCase       | `GetCourseById()`      |
| Private fields | \_camelCase      | `_courseRepository`    |
| Parameters     | camelCase        | `courseId`             |
| Interfaces     | I-prefix         | `ICourseRepository`    |
| Async methods  | Async suffix     | `GetCourseByIdAsync()` |
| Constants      | PascalCase       | `MaxRetryCount`        |
| Files          | Match class name | `CourseService.cs`     |

## Async Rules

- **Async all the way down** — No `.Result`, no `.Wait()`, no `Task.Run()` for IO
- **Always pass `CancellationToken`** in async method signatures
- **Use `ConfigureAwait(false)`** in library code only, not in ASP.NET controllers

## CQRS Structure

```text
Application/
├── Features/
│   └── Courses/
│       ├── Commands/
│       │   ├── CreateCourse/
│       │   │   ├── CreateCourseCommand.cs
│       │   │   ├── CreateCourseCommandHandler.cs
│       │   │   └── CreateCourseCommandValidator.cs
│       │   └── UpdateCourse/
│       │       └── ...
│       └── Queries/
│           └── GetCourseById/
│               ├── GetCourseByIdQuery.cs
│               ├── GetCourseByIdQueryHandler.cs
│               └── CourseDto.cs
```

## Error Handling

- Use Result pattern or custom exceptions — not bare `try/catch` everywhere
- Domain exceptions: `DomainException`, `NotFoundException`, `ConflictException`
- Global exception handler middleware maps exceptions to HTTP status codes
- Never expose stack traces or internal details in API responses

## EF Core

- Fluent API configuration in separate `EntityTypeConfiguration` classes
- Always use migrations, never `EnsureCreated()`
- Use `AsNoTracking()` for read-only queries
- Avoid lazy loading — use explicit `Include()` or projection

## Testing

- **xUnit** for test framework
- **NSubstitute** or **Moq** for mocking
- **TestContainers** for integration tests (real PostgreSQL, Redis)
- Test the service/handler layer, not the framework
- Naming: `MethodName_StateUnderTest_ExpectedBehavior`

```csharp
[Fact]
public async Task CreateCourse_WithValidData_ReturnsCourseId()
```

---

# Next.js Conventions

> Next.js and React specific patterns and standards.

Source: https://devplaybook.tansuasici.com/docs/conventions/nextjs

## Architecture: App Router

**App Router only** — no `pages/` directory.

```text
src/
├── app/
│   ├── [locale]/
│   │   ├── (portal-student)/
│   │   ├── (portal-instructor)/
│   │   ├── (portal-admin)/
│   │   ├── (auth)/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── api/            ← Route handlers (if needed)
│   └── globals.css
├── components/
│   ├── ui/             ← shadcn/ui primitives
│   ├── shared/         ← Reusable across portals
│   └── features/       ← Feature-specific components
├── lib/
│   ├── api/            ← API client functions
│   ├── hooks/          ← Custom React hooks
│   ├── stores/         ← Zustand stores
│   └── utils/          ← Pure utility functions
├── types/              ← TypeScript type definitions
└── messages/           ← i18n translation files (next-intl)
```

## Component Rules

1. **Server Components by default** — Only add `"use client"` when you need interactivity, browser APIs, or hooks
2. **Colocate** — Keep related files together (component + its types + its styles)
3. **One component per file** — Exception: small helper components used only by the parent
4. **Export named, not default** — `export function CourseCard()` not `export default function`
   - *Exception*: App Router route files (`page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`) require default exports per Next.js convention

## State Management

| Type         | Tool                  | When                                    |
| ------------ | --------------------- | --------------------------------------- |
| Server state | TanStack Query        | API data fetching, caching, mutations   |
| Client state | Zustand               | UI state (sidebar open, theme, filters) |
| Form state   | React Hook Form + Zod | All forms, always validated             |
| URL state    | `useSearchParams`     | Filters, pagination, sorting            |

**Never** use React Context for state that changes frequently. Zustand or URL state instead.

## Naming

| Element          | Convention                     | Example           |
| ---------------- | ------------------------------ | ----------------- |
| Files            | kebab-case                     | `course-card.tsx` |
| Components       | PascalCase                     | `CourseCard`      |
| Hooks            | camelCase with `use` prefix    | `useCourseData`   |
| Stores           | camelCase with `use` + `Store` | `useSidebarStore` |
| Types/Interfaces | PascalCase                     | `CourseResponse`  |
| Constants        | SCREAMING\_SNAKE               | `MAX_FILE_SIZE`   |
| CSS classes      | Tailwind utilities             | —                 |

## Styling

- **Tailwind CSS** for everything — no CSS modules, no styled-components
- **shadcn/ui** for base components — customize via Tailwind, don't fork
- **`cn()` helper** for conditional classes (from `lib/utils`)
- **No inline styles** — Use Tailwind classes

## i18n (Internationalization)

- **next-intl** for all user-facing text
- Never hardcode UI text — always use `t('key')`
- Translation files: `messages/tr.json`, `messages/en.json`
- Default locale: Turkish (`tr`)

## Data Fetching

```typescript
// Server Component — fetch directly
async function CoursePage({ params }: { params: { id: string } }) {
  const course = await getCourse(params.id);
  return <CourseDetail course={course} />;
}

// Client Component — TanStack Query
function CourseList() {
  const { data, isLoading } = useQuery({
    queryKey: ['courses'],
    queryFn: () => apiClient.getCourses(),
  });
}
```

## Forms

Always: React Hook Form + Zod schema

```typescript
const schema = z.object({
  title: z.string().min(1, 'Required').max(200),
  description: z.string().optional(),
});

type FormData = z.infer<typeof schema>;
```

## Testing

- **Vitest** for unit tests
- **Playwright** for E2E tests
- Test user interactions, not implementation details
- Mock API calls, not components

---

# Python Conventions

> Python coding standards and project structure.

Source: https://devplaybook.tansuasici.com/docs/conventions/python

## Version & Tooling

- **Python 3.11+** — Use modern features (type hints, match statements, ExceptionGroups)
- **FastAPI** for web APIs
- **Pydantic v2** for data validation and settings
- **Ruff** for linting + formatting (replaces flake8, black, isort)
- **pytest** for testing
- **mypy** for type checking

## Project Structure

```text
project/
├── src/
│   └── project_name/
│       ├── __init__.py
│       ├── main.py           ← FastAPI app entrypoint
│       ├── config.py         ← Settings via pydantic-settings
│       ├── api/
│       │   ├── routes/       ← Route handlers
│       │   └── deps.py       ← Dependency injection
│       ├── models/           ← Pydantic models (request/response)
│       ├── services/         ← Business logic
│       └── core/             ← Shared utilities
├── tests/
│   ├── conftest.py
│   ├── test_services/
│   └── test_api/
├── pyproject.toml            ← Single config file (deps, ruff, mypy, pytest)
├── requirements.txt          ← Pinned deps for CI/deployment
└── Dockerfile
```

## Naming

| Element        | Convention         | Example              |
| -------------- | ------------------ | -------------------- |
| Files/modules  | snake\_case        | `course_service.py`  |
| Functions      | snake\_case        | `get_course_by_id()` |
| Classes        | PascalCase         | `CourseService`      |
| Constants      | SCREAMING\_SNAKE   | `MAX_CHUNK_SIZE`     |
| Private        | leading underscore | `_parse_document()`  |
| Type variables | PascalCase         | `T`, `ResponseT`     |

## Type Hints

**Required everywhere.** No untyped public functions.

```python
def process_document(
    file_path: Path,
    chunk_size: int = 512,
    overlap: int = 50,
) -> list[DocumentChunk]:
    ...
```

Use modern syntax:

- `list[str]` not `List[str]`
- `dict[str, int]` not `Dict[str, int]`
- `str | None` not `Optional[str]`

## Async

- All FastAPI route handlers should be `async def`
- Use `asyncio` for concurrent IO operations
- Use `httpx.AsyncClient` for HTTP calls (not `requests`)
- Never mix sync and async — pick one per service

## Configuration

Use pydantic-settings for all config:

```python
class Settings(BaseSettings):
    database_url: str
    redis_url: str = "redis://localhost:6379"
    debug: bool = False

    model_config = SettingsConfigDict(env_file=".env")
```

## Error Handling

- Use custom exception classes, not bare `raise Exception`
- FastAPI exception handlers for HTTP error responses
- Log exceptions with context, not just the message
- Never silently swallow exceptions with bare `except:`

## Testing

- **pytest** with async support (`pytest-asyncio`)
- Fixtures for shared setup
- Use `httpx.AsyncClient` with `ASGITransport` for API tests
- Naming: `test_<function>_<scenario>_<expected>`

```python
async def test_process_document_with_valid_pdf_returns_chunks():
    ...
```

## Dependencies

- Pin exact versions in `requirements.txt` for reproducibility
- Use ranges in `pyproject.toml` for library projects
- `pip-compile` or `uv` for lock file generation
- Review and update dependencies monthly

---

# Docker

> Container standards, Dockerfile patterns, and compose conventions.

Source: https://devplaybook.tansuasici.com/docs/conventions/docker

## Dockerfile Best Practices

### Multi-Stage Builds

Always use multi-stage builds to keep images small:

```dockerfile
# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY *.sln .
COPY src/**/*.csproj ./
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish

# Stage 2: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
COPY --from=build /app/publish .
EXPOSE 8080
ENTRYPOINT ["dotnet", "Api.dll"]
```

### Rules

1. **Pin base image versions** — `node:22-alpine`, not `node:latest`

2. **Use alpine variants** when possible — smaller image, smaller attack surface

3. **Don't run as root** — Add a non-root user:

   ```dockerfile
   RUN adduser --disabled-password --gecos "" appuser
   USER appuser
   ```

4. **Order layers by change frequency** — Dependencies first (cached), source code last

5. **Use .dockerignore** — Exclude `node_modules/`, `bin/`, `obj/`, `.git/`, `.env`

6. **One process per container** — Don't run web server + background worker in the same container

7. **Health checks in Dockerfile**:

   ```dockerfile
   HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
     CMD curl -f http://localhost:8080/health || exit 1
   ```

## Docker Compose

### Development Stack Template

```yaml
services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    ports:
      - "${DB_PORT:-5432}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:8-alpine
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
  redis_data:
```

### Compose Rules

1. **Use `.env` file** for all configurable values (ports, credentials, versions)
2. **Add health checks** to every service — dependent services use `depends_on: condition: service_healthy`
3. **Named volumes** for persistent data — never bind-mount database data directories
4. **Pin image versions** — `postgres:17-alpine`, not `postgres:latest`
5. **Don't expose ports in production** that should be internal-only

### Environment Variables

```bash
# .env.example (commit this)
DB_USER=myapp
DB_PASSWORD=change_me
DB_NAME=myapp_dev
DB_PORT=5432
REDIS_PORT=6379

# .env (do NOT commit)
DB_USER=myapp
DB_PASSWORD=actual_secure_password
DB_NAME=myapp_dev
DB_PORT=5432
REDIS_PORT=6379
```

## Image Naming

```text
ghcr.io/<org>/<service>:<tag>
```

| Tag          | When                   | Example                       |
| ------------ | ---------------------- | ----------------------------- |
| `latest`     | Latest build from main | `ghcr.io/org/api:latest`      |
| `sha-<hash>` | Specific commit        | `ghcr.io/org/api:sha-abc1234` |
| `v1.2.0`     | Release version        | `ghcr.io/org/api:v1.2.0`      |

## .dockerignore

```text
.git
.github
node_modules
bin
obj
.env
.env.*
*.md
tests
**/*.test.*
.DS_Store
```

## Common Mistakes

| Mistake                           | Fix                                                           |
| --------------------------------- | ------------------------------------------------------------- |
| Running as root                   | Add `USER` instruction                                        |
| `COPY . .` before restore/install | Copy dependency files first, then `COPY . .`                  |
| No .dockerignore                  | Add one — `node_modules` in an image is a build time disaster |
| `latest` tag in production        | Pin to specific version or SHA                                |
| Secrets in build args             | Use runtime env vars or secrets mount                         |
| Giant images                      | Use multi-stage + alpine                                      |

---

# Git Hooks

> Pre-commit, commit-msg, and pre-push hook standards.

Source: https://devplaybook.tansuasici.com/docs/conventions/git-hooks

## Purpose

Git hooks run automated checks before commits and pushes, catching problems before they reach the remote. Think of them as a local CI that runs instantly.

## Recommended Hooks

| Hook         | When                         | What to Run                          |
| ------------ | ---------------------------- | ------------------------------------ |
| `pre-commit` | Before each commit           | Lint + format staged files           |
| `commit-msg` | After writing commit message | Validate Conventional Commits format |
| `pre-push`   | Before pushing to remote     | Run tests                            |

## Setup by Stack

### Node.js / Next.js — Husky + lint-staged

```bash
# Install
npm install --save-dev husky lint-staged

# Initialize husky
npx husky init
```

`.husky/pre-commit`:

```bash
npx lint-staged
```

`package.json`:

```json
{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml}": ["prettier --write"]
  }
}
```

`.husky/commit-msg`:

```bash
npx --no -- commitlint --edit "$1"
```

Install commitlint:

```bash
npm install --save-dev @commitlint/cli @commitlint/config-conventional
```

`commitlint.config.js`:

```javascript
export default { extends: ['@commitlint/config-conventional'] };
```

### .NET — Husky.Net

```bash
dotnet tool install Husky
dotnet husky install
dotnet husky add pre-commit -c "dotnet format --verify-no-changes"
dotnet husky add pre-commit -c "dotnet build --no-restore"
```

### Python — pre-commit

```bash
pip install pre-commit
```

`.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
```

```bash
pre-commit install
```

## Rules

1. **Hooks should be fast** — Under 5 seconds. If it takes longer, run only on staged files.
2. **Only check staged files** — Don't lint the entire codebase on every commit.
3. **Commit hook config to the repo** — `.husky/`, `.pre-commit-config.yaml` should be versioned.
4. **Document setup** — New developers should know to run the install command.
5. **Never skip hooks** — Don't use `--no-verify` unless you have a very good reason (and you probably don't).

## Troubleshooting

| Problem                        | Fix                                                                       |
| ------------------------------ | ------------------------------------------------------------------------- |
| Hook not running               | Run the install command again (`npx husky install`, `pre-commit install`) |
| Hook too slow                  | Use lint-staged to check only staged files, not the whole repo            |
| False positive blocking commit | Fix the issue. Don't skip the hook.                                       |
| Team member doesn't have hooks | Add `prepare` script: `"prepare": "husky"` in package.json                |

---

# Documentation Standards

> README templates, API docs, and inline documentation rules.

Source: https://devplaybook.tansuasici.com/docs/conventions/documentation

## What to Document

| Type                       | Where                                                                    | When                                      |
| -------------------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| **API Reference**          | OpenAPI/Swagger (auto-generated)                                         | Always for public APIs                    |
| **Architecture Decisions** | `docs/adr/` or [architecture/decisions.md](/docs/architecture/decisions) | When making significant technical choices |
| **README**                 | Root of every repo                                                       | Always                                    |
| **Inline Comments**        | In the code                                                              | Only when the "why" isn't obvious         |
| **Runbooks**               | Wiki or `docs/runbooks/`                                                 | For operational procedures                |
| **CLAUDE.md**              | Root of every repo                                                       | For AI-assisted development               |

## README Template

Every project README should include:

```markdown
# Project Name

One-line description of what this project does.

## Quick Start

### Prerequisites
- Node.js 20+
- Docker & Docker Compose
- PostgreSQL 16 (via Docker)

### Setup
\`\`\`bash
git clone <repo-url>
cd <project>
cp .env.example .env
docker compose up -d
npm install
npm run dev
\`\`\`

### Running Tests
\`\`\`bash
npm test              # unit tests
npm run test:e2e      # end-to-end tests
\`\`\`

## Project Structure

\`\`\`
src/
├── modules/     ← Feature modules
├── shared/      ← Shared utilities
└── config/      ← Configuration
\`\`\`

## API Documentation

Available at `/swagger` when running locally.

## Deployment

See [CI/CD pipeline](.github/workflows/ci.yml) for automated deployment.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](https://github.com/tansuasici/dev-playbook/blob/main/LICENSE)
```

## API Documentation

### OpenAPI/Swagger

- **Auto-generate** from code annotations — don't maintain a separate spec file
- **Include examples** for request/response bodies
- **Document all error responses**, not just the happy path
- **Group endpoints** by resource or feature

```csharp
// .NET — Swagger annotations
[HttpPost]
[ProducesResponseType(typeof(CourseDto), StatusCodes.Status201Created)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
public async Task<IActionResult> CreateCourse([FromBody] CreateCourseRequest request)
```

```typescript
// Next.js / Express — JSDoc or zod-to-openapi
/**
 * @openapi
 * /api/courses:
 *   post:
 *     summary: Create a new course
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/CreateCourseRequest'
 *     responses:
 *       201:
 *         description: Course created successfully
 *       400:
 *         description: Validation error
 */
```

```python
# Python — FastAPI auto-generates OpenAPI
@router.post("/courses", response_model=CourseResponse, status_code=201)
async def create_course(request: CreateCourseRequest):
    """Create a new course.

    Raises:
        HTTPException(400): Invalid input
        HTTPException(409): Duplicate course title
    """
```

## Inline Comments

### When to Comment

- **Why**, not what — the code already says what it does
- **Business rules** that aren't obvious from code
- **Workarounds** with links to issues or tickets
- **Performance decisions** that look wrong but are intentional
- **Regex patterns** — always explain what they match

### When NOT to Comment

- Obvious code (`i++ // increment i`)
- Function names that are self-explanatory
- TODO/FIXME without issue references
- Commented-out code — delete it, git has history

### Examples

```csharp
// GOOD — explains WHY
// Tenant isolation: RLS handles filtering, but we double-check here
// because admin endpoints bypass RLS for cross-tenant reports
if (!user.IsAdmin && course.TenantId != user.TenantId)
    throw new ForbiddenException();

// GOOD — explains business rule
// Students can unenroll within 14 days of enrollment (refund policy)
if (enrollment.CreatedAt.AddDays(14) < DateTime.UtcNow)
    throw new BusinessRuleException("Unenrollment period has expired");

// BAD — states the obvious
// Check if user is null
if (user == null) ...

// BAD — no issue reference
// TODO: fix this later
```

## CLAUDE.md

Every project should have a `CLAUDE.md` at the root for AI-assisted development.

See [templates/claude-md-starter.md](/docs/templates/claude-md-starter) for the starter template.

### Must Include

- Project description and tech stack
- How to build, test, and run
- Key architecture decisions
- Link to this playbook for standards
- Project-specific conventions not covered by the playbook

## Changelogs

### For Libraries / Packages

Follow [Keep a Changelog](https://keepachangelog.com/) format:

```markdown
## [1.2.0] - 2025-03-15

### Added
- Course capacity limits

### Fixed
- Login redirect with query parameters
```

### For Applications

Use **release notes** tied to version tags instead of maintaining a CHANGELOG file. The git history and PR descriptions are the changelog.

## Anti-Patterns

- **No README** — Every project needs one, even internal tools
- **Stale documentation** — Outdated docs are worse than no docs. Keep it updated or delete it.
- **Documentation in a separate system** — Keep docs close to code (same repo) when possible
- **Over-documenting internals** — Code should be self-explanatory. Document interfaces, not implementations.
- **Screenshots without context** — Always explain what the screenshot shows and when it was taken

---

# Environment Management

> Dev/staging/prod environment setup and feature flags.

Source: https://devplaybook.tansuasici.com/docs/conventions/environment-management

## Environments

| Environment    | Purpose                | Deploys From                  | Who Uses It          |
| -------------- | ---------------------- | ----------------------------- | -------------------- |
| **Local**      | Development            | Developer machine             | Individual developer |
| **Staging**    | Pre-production testing | `main` branch (auto)          | Team, QA             |
| **Production** | Live users             | Version tags (manual trigger) | Everyone             |

### Optional Environments

| Environment   | When to Use                                     |
| ------------- | ----------------------------------------------- |
| **Preview**   | Per-PR deployments for review (Vercel, Netlify) |
| **QA**        | Dedicated QA testing with controlled data       |
| **Load Test** | Performance testing with production-like data   |

## Configuration Management

### Environment Variables

Use `.env` files for local development, environment variables or secrets managers for deployed environments.

```text
.env                  → Local defaults (git-ignored)
.env.example          → Template with placeholder values (committed)
.env.test             → Test-specific overrides (committed, no secrets)
```

### .env.example

Always maintain a `.env.example` with every variable documented:

```bash
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Redis
REDIS_URL=redis://localhost:6379

# Auth
JWT_SECRET=your-secret-here
JWT_EXPIRY_MINUTES=15

# External Services
STORAGE_BUCKET=my-bucket
STORAGE_ENDPOINT=http://localhost:9000

# Feature Flags
FEATURE_NEW_DASHBOARD=false
FEATURE_AI_CHAT=false

# App
APP_URL=http://localhost:3000
API_URL=http://localhost:5000
LOG_LEVEL=Information
```

### Rules

- **Never commit `.env` files** with real values
- **Every new env var** must be added to `.env.example` in the same PR
- **Use descriptive names**: `DATABASE_URL` not `DB`, `JWT_SECRET` not `SECRET`
- **Document expected format** in comments when not obvious
- **Group by category** (database, auth, external services, features)

### Accessing Config

```csharp
// .NET — Use Options pattern, never read env vars directly in services
public class JwtSettings
{
    public string Secret { get; set; }
    public int ExpiryMinutes { get; set; }
}

// Registration
builder.Services.Configure<JwtSettings>(builder.Configuration.GetSection("Jwt"));
```

```typescript
// TypeScript — Validate at startup, fail fast
import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  NODE_ENV: z.enum(['development', 'test', 'production']),
});

export const env = envSchema.parse(process.env);
```

```python
# Python — Use pydantic-settings
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    jwt_secret: str
    log_level: str = "INFO"

    class Config:
        env_file = ".env"

settings = Settings()
```

## Feature Flags

Use feature flags to control feature rollout without redeploying.

### When to Use

- Releasing a feature incrementally (% of users)
- Gating a feature behind a tenant or role
- Quick kill switch for risky features
- A/B testing

### Implementation

```typescript
// Simple env-based flags (good for small projects)
const features = {
  newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
  aiChat: process.env.FEATURE_AI_CHAT === 'true',
};

if (features.newDashboard) {
  // render new dashboard
}
```

```csharp
// .NET — Feature Management library
builder.Services.AddFeatureManagement();

// Usage
if (await _featureManager.IsEnabledAsync("NewDashboard"))
{
    // new behavior
}
```

### Rules

- **Name clearly**: `FEATURE_NEW_DASHBOARD` not `FLAG_1`
- **Default to off** for new features
- **Clean up after rollout** — remove the flag and dead code path once the feature is fully launched
- **Log flag evaluations** — know which users see which features
- **Document every flag** with purpose, owner, and expected removal date

### Flag Lifecycle

```text
Created → Testing → Rollout (10% → 50% → 100%) → Cleanup (remove flag + old code)
```

## Secrets Management

### By Environment

| Environment    | Strategy                                                        |
| -------------- | --------------------------------------------------------------- |
| **Local**      | `.env` file (git-ignored)                                       |
| **CI/CD**      | GitHub Actions Secrets / pipeline variables                     |
| **Staging**    | Secrets manager (Azure Key Vault, AWS Secrets Manager, Doppler) |
| **Production** | Secrets manager with audit logging and rotation                 |

### Rules

- **Never hardcode secrets** in source code
- **Rotate secrets** after team member departures
- **Use different secrets per environment** — staging and production must never share
- **Audit access** — know who can read production secrets
- **Least privilege** — each service gets only the secrets it needs

## Environment Parity

Keep environments as similar as possible to catch issues early.

### What Must Match

- Same database engine and version (PostgreSQL 16, not SQLite for dev)
- Same cache engine (Redis, not in-memory for dev)
- Same message broker
- Same container runtime

### What Can Differ

- Resource allocation (fewer replicas, smaller instances)
- External service endpoints (sandbox APIs vs production)
- Data volume (subset of production data, anonymized)
- Domain names and certificates

### Docker Compose for Local Parity

```yaml
# docker-compose.yml — mirrors production dependencies
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
```

## Anti-Patterns

- **"Works on my machine"** — Use Docker Compose to ensure local parity with production
- **Shared staging database** — Each PR/branch should ideally get isolated data
- **Secrets in code or git history** — If it happened, rotate the secret immediately
- **No `.env.example`** — New developers shouldn't have to guess what variables are needed
- **Feature flags that live forever** — Set a removal date when creating the flag

---

# Accessibility (a11y)

> Web accessibility standards and WCAG compliance.

Source: https://devplaybook.tansuasici.com/docs/conventions/accessibility

## Core Principle

**Every user should be able to use the application regardless of ability.** Accessibility is not optional — it's a quality requirement like security or performance.

Target: **WCAG 2.1 Level AA** compliance.

## Semantic HTML

Use the right element for the job. Semantic HTML gives you accessibility for free.

```html
<!-- GOOD — semantic, accessible by default -->
<button onClick={handleSubmit}>Submit</button>
<nav aria-label="Main navigation">...</nav>
<main>...</main>
<form onSubmit={handleSubmit}>...</form>
<a href="/courses">View courses</a>

<!-- BAD — div soup, requires manual ARIA -->
<div onClick={handleSubmit} class="button">Submit</div>
<div class="nav">...</div>
<div class="main-content">...</div>
<div onClick={() => navigate('/courses')}>View courses</div>
```

### Heading Hierarchy

```html
<!-- GOOD — logical hierarchy -->
<h1>Course Dashboard</h1>
  <h2>Active Courses</h2>
    <h3>Introduction to Psychology</h3>
  <h2>Completed Courses</h2>

<!-- BAD — skipping levels for styling -->
<h1>Course Dashboard</h1>
  <h4>Active Courses</h4>  <!-- Skipped h2, h3 -->
```

Never skip heading levels. Use CSS for visual sizing, not heading tags.

## Keyboard Navigation

### Requirements

- All interactive elements must be **focusable** and **operable** with keyboard
- **Tab order** must follow visual order (don't rearrange with `tabIndex > 0`)
- **Focus must be visible** — never remove focus outlines without replacement
- **Escape** should close modals, dropdowns, and popovers
- **Enter/Space** should activate buttons and links

### Focus Management

```typescript
// After opening a modal, move focus into it
function openModal() {
  setIsOpen(true);
  // Focus the first focusable element in the modal
  requestAnimationFrame(() => {
    modalRef.current?.querySelector<HTMLElement>('[tabindex="-1"], button, input')?.focus();
  });
}

// After closing, return focus to the trigger element
function closeModal() {
  setIsOpen(false);
  triggerRef.current?.focus();
}
```

### Focus Trap

Modals and dialogs must trap focus — Tab should cycle within the modal, not escape to the page behind it.

```typescript
// Use a library like @radix-ui/react-dialog or headlessui
// They handle focus trapping, Escape to close, and focus restoration
import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      {/* Focus is automatically trapped here */}
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>
```

## Images and Media

### Images

```html
<!-- Informative image — describe the content -->
<img src="chart.png" alt="Bar chart showing enrollment increased 40% in Q3 2025" />

<!-- Decorative image — empty alt -->
<img src="divider.png" alt="" />

<!-- Complex image — use figure + figcaption -->
<figure>
  <img src="architecture.png" alt="System architecture diagram" />
  <figcaption>
    Three microservices communicate via message queue.
    The API Gateway routes requests to Course, User, and Analytics services.
  </figcaption>
</figure>
```

### Video and Audio

- Provide **captions** for all video content
- Provide **transcripts** for audio content
- Never autoplay media with sound
- Provide playback controls (play, pause, volume, seek)

## Forms

```html
<!-- GOOD — labeled, described, with error handling -->
<div>
  <label htmlFor="email">Email address</label>
  <input
    id="email"
    type="email"
    aria-describedby="email-hint email-error"
    aria-invalid={hasError}
    required
  />
  <p id="email-hint">We'll never share your email</p>
  {hasError && <p id="email-error" role="alert">Please enter a valid email</p>}
</div>

<!-- BAD — no label, no error association -->
<input type="email" placeholder="Email" />
<span class="error">Invalid email</span>
```

### Form Rules

- Every input must have a visible `<label>` (not just `placeholder`)
- Use `aria-describedby` for hints and error messages
- Use `aria-invalid` to indicate error state
- Use `role="alert"` for dynamic error messages (screen readers announce them)
- Group related inputs with `<fieldset>` and `<legend>`
- Mark required fields with `required` attribute and visual indicator

## Color and Contrast

- **Minimum contrast ratio**: 4.5:1 for normal text, 3:1 for large text (18px+ bold)
- **Don't rely on color alone** to convey information — add icons, text, or patterns
- Support `prefers-color-scheme` and `prefers-reduced-motion`

```css
/* Respect user preferences */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #1a1a2e;
    --text: #e0e0e0;
  }
}
```

### Status Indicators

```html
<!-- BAD — color only -->
<span style="color: red">Failed</span>
<span style="color: green">Passed</span>

<!-- GOOD — color + icon + text -->
<span class="status-failed">&#10007; Failed</span>
<span class="status-passed">&#10003; Passed</span>
```

## ARIA (When HTML Isn't Enough)

Use ARIA only when native HTML elements can't do the job.

| Pattern            | ARIA                                                               |
| ------------------ | ------------------------------------------------------------------ |
| Custom dropdown    | `role="listbox"`, `role="option"`, `aria-expanded`                 |
| Tabs               | `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected` |
| Toast/notification | `role="alert"` or `aria-live="polite"`                             |
| Loading state      | `aria-busy="true"`, `aria-live="polite"`                           |
| Icon-only button   | `aria-label="Close dialog"`                                        |

### Rules

- **First rule of ARIA**: Don't use ARIA if native HTML works
- **Don't change semantics**: `<button role="link">` — just use `<a>`
- **Keep ARIA states updated**: If `aria-expanded="true"`, update it when collapsed
- **Test with a screen reader**: ARIA attributes are only useful if they work in practice

## Testing

### Automated Testing

```bash
# Axe — catches ~30% of accessibility issues
npm install -D @axe-core/playwright  # for Playwright
npm install -D jest-axe              # for Jest/Vitest

# Lighthouse — includes accessibility audit
npx lighthouse http://localhost:3000 --only-categories=accessibility
```

```typescript
// Playwright accessibility test
import AxeBuilder from '@axe-core/playwright';

test('course page has no accessibility violations', async ({ page }) => {
  await page.goto('/courses');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});
```

### Manual Testing Checklist

- [ ] Navigate the entire page using only keyboard (Tab, Enter, Escape, Arrow keys)
- [ ] Test with a screen reader (VoiceOver on macOS, NVDA on Windows)
- [ ] Zoom to 200% — is the layout still usable?
- [ ] Check color contrast ratios with browser DevTools
- [ ] Disable CSS — does the content still make sense?

## Anti-Patterns

- **`outline: none` without replacement** — Users can't see where focus is
- **Placeholder as label** — Disappears when typing, not announced by all screen readers
- **Click handlers on divs** — Use `<button>` or `<a>`, not `<div onClick>`
- **Images without alt text** — Screen readers say "image" with no context
- **Autoplaying media** — Disorienting and disruptive for many users
- **Infinite scroll without alternative** — Keyboard users can never reach the footer

---

# Internationalization (i18n)

> Internationalization and localization approach.

Source: https://devplaybook.tansuasici.com/docs/conventions/i18n

## Core Principle

**Never hardcode user-facing strings.** Even if you only support one language today, extracting strings into translation files costs almost nothing and makes adding languages trivial later.

## Architecture

```text
src/
├── locales/
│   ├── en/
│   │   ├── common.json        ← Shared strings (buttons, nav, errors)
│   │   ├── courses.json       ← Feature-specific strings
│   │   └── auth.json
│   ├── tr/
│   │   ├── common.json
│   │   ├── courses.json
│   │   └── auth.json
│   └── index.ts               ← i18n configuration
```

### Translation File Format

```json
{
  "courses": {
    "title": "My Courses",
    "empty": "You haven't enrolled in any courses yet.",
    "enrollButton": "Enroll Now",
    "capacity": "{{remaining}} of {{total}} spots remaining",
    "filters": {
      "all": "All",
      "active": "Active",
      "completed": "Completed"
    }
  }
}
```

### Key Naming Convention

- **Dot notation** for nested keys: `courses.filters.active`
- **Feature-scoped**: `courses.title`, not `title`
- **Descriptive**: `courses.enrollButton`, not `courses.btn1`
- **Consistent**: Same structure across all languages

## Implementation

### Next.js — next-intl or next-i18next

```typescript
// Using next-intl
import { useTranslations } from 'next-intl';

export default function CoursesPage() {
  const t = useTranslations('courses');

  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('capacity', { remaining: 5, total: 30 })}</p>
      <button>{t('enrollButton')}</button>
    </div>
  );
}
```

### .NET — Resource Files or JSON

```csharp
// Using IStringLocalizer
public class CoursesController : ControllerBase
{
    private readonly IStringLocalizer<CoursesController> _localizer;

    [HttpGet]
    public IActionResult Get()
    {
        var message = _localizer["CourseFull"];
        return Ok(new { message });
    }
}
```

### Python — gettext or custom

```python
# Using gettext
from gettext import gettext as _

def get_enrollment_message(remaining: int, total: int) -> str:
    return _("{remaining} of {total} spots remaining").format(
        remaining=remaining, total=total
    )
```

## Formatting

### Dates and Times

**Never format dates manually.** Use `Intl.DateTimeFormat` or equivalent library.

```typescript
// GOOD — locale-aware
const formatted = new Intl.DateTimeFormat('tr-TR', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
}).format(date);
// → "15 Mart 2025"

// BAD — hardcoded format
const formatted = `${date.getMonth()}/${date.getDate()}/${date.getFullYear()}`;
// → "3/15/2025" (always US format)
```

### Numbers and Currency

```typescript
// Numbers
new Intl.NumberFormat('tr-TR').format(1234567.89);
// → "1.234.567,89"

// Currency
new Intl.NumberFormat('tr-TR', { style: 'currency', currency: 'TRY' }).format(99.90);
// → "₺99,90"
```

### Pluralization

Don't assume all languages pluralize like English (just add "s").

```json
// English
{
  "studentCount": {
    "zero": "No students",
    "one": "1 student",
    "other": "{{count}} students"
  }
}

// Turkish (no grammatical plural for counted nouns)
{
  "studentCount": {
    "zero": "Ogrenci yok",
    "one": "1 ogrenci",
    "other": "{{count}} ogrenci"
  }
}
```

```typescript
// next-intl handles ICU plural syntax
// common.json: "studentCount": "{count, plural, =0 {No students} one {1 student} other {# students}}"
t('studentCount', { count: 5 });
```

## Content Rules

### Do

- **Extract ALL user-facing strings** — buttons, labels, headings, error messages, tooltips
- **Use variables for dynamic content**: `"Welcome, {{name}}"` not `"Welcome, " + name`
- **Support RTL** — Arabic, Hebrew need right-to-left layout
- **Handle text expansion** — German text is \~30% longer than English, design with flexibility
- **Use Unicode** — UTF-8 everywhere (database, files, API responses)
- **Store dates in UTC** — convert to local timezone only in the UI

### Don't

- **Don't concatenate strings**: `t('hello') + ' ' + name` — word order differs across languages
- **Don't embed HTML in translations**: `"Click <b>here</b>"` — use components with slots instead
- **Don't hardcode sort order** — alphabetical order varies by locale
- **Don't assume text direction** — design layouts that adapt to RTL
- **Don't use flags for languages** — a flag represents a country, not a language

## Language Detection

Priority order:

1. **User preference** — stored in profile/settings
2. **URL parameter or path** — `/en/courses` or `?lang=en`
3. **Accept-Language header** — browser default
4. **Fallback** — default language (English)

```typescript
// Next.js middleware for locale detection
import createMiddleware from 'next-intl/middleware';

export default createMiddleware({
  locales: ['en', 'tr'],
  defaultLocale: 'en',
});
```

## Translation Workflow

1. Developer adds keys to the **default language** (English) file
2. Missing translations fall back to the default language
3. Translation files are reviewed in PRs like code
4. Consider professional translation for user-facing content
5. Use tools like Crowdin, Lokalise, or Phrase for team translation management

## Anti-Patterns

- **Hardcoded strings in components** — Always use translation functions
- **Date formatting with template literals** — Use `Intl.DateTimeFormat`
- **Splitting sentences across multiple keys** — Word order changes across languages
- **Ignoring text expansion in designs** — German, Finnish, and other languages need more space
- **Using machine translation without review** — Automated translations need human validation

---

# Branching Strategy

> Git branching model and workflow.

Source: https://devplaybook.tansuasici.com/docs/process/branching

## Branch Types

| Branch   | Pattern               | Source | Merges Into   | Purpose                                    |
| -------- | --------------------- | ------ | ------------- | ------------------------------------------ |
| Main     | `main`                | —      | —             | Production-ready code. Always deployable.  |
| Feature  | `feat/<issue-slug>`   | main   | main (via PR) | New features                               |
| Fix      | `fix/<issue-slug>`    | main   | main (via PR) | Bug fixes                                  |
| Hotfix   | `hotfix/<issue-slug>` | main   | main (via PR) | Critical production fixes                  |
| Chore    | `chore/<slug>`        | main   | main (via PR) | Dependency updates, CI changes, cleanup    |
| Docs     | `docs/<slug>`         | main   | main (via PR) | Documentation changes                      |
| Refactor | `refactor/<slug>`     | main   | main (via PR) | Code restructuring without behavior change |

## Rules

1. **Never push directly to `main`** — All changes go through a PR.
2. **One branch per issue** — Branch name should reference the issue or describe the work.
3. **Keep branches short-lived** — Merge within days, not weeks. Long-lived branches cause merge hell.
4. **Delete branches after merge** — No stale branches. Clean up both local and remote.
5. **Pull before branch** — Always create branches from an up-to-date `main`.

## Naming Convention

```text
<type>/<short-descriptive-slug>
```

**Examples**:

- `feat/user-authentication`
- `fix/login-redirect-loop`
- `hotfix/payment-null-reference`
- `chore/upgrade-dotnet-10`
- `docs/api-reference`
- `refactor/extract-email-service`

**Rules**:

- Lowercase only
- Hyphens for word separation (no underscores, no spaces)
- No issue numbers in branch names (the PR links to the issue)
- Keep it under 50 characters

## Workflow

```text
1. Pick an issue from the board
2. Move issue to "In Progress"
3. Pull latest main:     git checkout main && git pull
4. Create branch:        git checkout -b feat/my-feature
5. Do the work, commit often
6. Push:                 git push -u origin feat/my-feature
7. Open PR referencing the issue
8. CI passes → merge
9. Delete branch:        git branch -d feat/my-feature
                         git push origin --delete feat/my-feature
```

## When You Don't Need a Branch

- Truly trivial changes (typo in README, comment fix) can still use a branch, but if the change is \\< 3 lines and the project is solo, a direct push with a proper commit message is acceptable. **This is the exception, not the rule.**

## Develop Branch?

Not needed for small-to-medium projects with a solo developer or small team. Main-based flow with feature branches is simpler and sufficient. Consider a `develop` branch only when:

- Multiple people work on unrelated features simultaneously
- You need a staging environment that tracks a separate branch
- Release cycles require a stabilization period

---

# Commit Conventions

> Conventional commits and message format.

Source: https://devplaybook.tansuasici.com/docs/process/commits

## Format: Conventional Commits

```text
<type>: <description>

[optional body]

[optional footer]
```

## Types

| Type       | When to Use                              | Example                                          |
| ---------- | ---------------------------------------- | ------------------------------------------------ |
| `feat`     | New feature or capability                | `feat: add user registration flow`               |
| `fix`      | Bug fix                                  | `fix: resolve null reference in payment service` |
| `docs`     | Documentation only                       | `docs: add API authentication guide`             |
| `refactor` | Code change that neither fixes nor adds  | `refactor: extract email sending into service`   |
| `perf`     | Performance improvement                  | `perf: add database index for user lookups`      |
| `test`     | Adding or updating tests                 | `test: add unit tests for OrderService`          |
| `chore`    | Build, CI, dependencies, tooling         | `chore: upgrade to .NET 10`                      |
| `style`    | Formatting, whitespace (no logic change) | `style: fix indentation in auth controller`      |
| `ci`       | CI/CD changes                            | `ci: add PostgreSQL service to test pipeline`    |
| `revert`   | Reverting a previous commit              | `revert: feat: add user registration flow`       |

## Rules

1. **Description is imperative mood** — "add feature" not "added feature" or "adds feature"
2. **Lowercase first letter** — `feat: add...` not `feat: Add...`
3. **No period at the end** — `feat: add auth` not `feat: add auth.`
4. **Max 72 characters** for the first line
5. **One concern per commit** — Don't mix a feature, a fix, and a refactor in one commit
6. **Language: English** — All commit messages in English, regardless of project language

## Breaking Changes

Use `!` after the type or add `BREAKING CHANGE:` in the footer:

```text
feat!: change authentication to OAuth2

BREAKING CHANGE: JWT token format has changed. All existing tokens will be invalidated.
```

## Body (Optional)

Use the body to explain **why**, not what. The diff shows what changed.

```text
fix: prevent duplicate enrollment for same course

Students could enroll multiple times by rapidly clicking the enroll button.
Added a unique constraint on (StudentId, CourseId) and a client-side debounce.
```

## Co-Authorship

When working with AI assistants:

```text
feat: implement course analytics dashboard

Co-Authored-By: Claude <noreply@anthropic.com>
```

## What NOT to Do

```text
# Too vague
fix: fix bug
feat: update code
chore: changes

# Too broad (multiple concerns)
feat: add auth, fix login bug, update deps

# Not imperative
feat: added user registration
feat: adding user registration

# Not English
feat: kullanici kayit eklendi
```

## Commit Frequency

- Commit when you have a logical unit of work complete
- Don't commit broken code to shared branches
- It's fine to have many small commits on a feature branch — they tell the story
- Squash only if the PR has truly noisy WIP commits

---

# Pull Requests

> PR creation, review, and merge standards.

Source: https://devplaybook.tansuasici.com/docs/process/pull-requests

## Core Rule

**Every change reaches `main` through a PR.** Even solo developers benefit from the audit trail, CI gate, and forced pause to review.

## PR Creation

### Title

- Keep under 70 characters
- Use imperative mood: "Add user auth" not "Added user auth"
- Prefix with type if helpful: `feat: Add user auth`, `fix: Resolve login loop`

### Body Structure

Every PR must have:

```markdown
## Summary
- <1-3 bullet points explaining what this PR does and why>

## Changes
- <List of significant changes, not a file-by-file diff>

## Test Plan
- [ ] Unit tests pass
- [ ] Manual testing done for <scenario>
- [ ] Edge cases considered: <list>

## Related
- Closes #<issue-number>
```

### Linking Issues

Always reference the issue:

- `Closes #42` — auto-closes the issue on merge
- `Fixes #42` — same behavior
- `Related to #42` — links without auto-closing (use for partial work)

## PR Rules

1. **One concern per PR** — Don't mix features, fixes, and refactors
2. **CI must pass** — Never merge with failing checks
3. **Keep PRs small** — Under 400 lines changed is ideal. Over 800 needs a good reason.
4. **No WIP merges** — If it's not ready, mark as Draft PR
5. **Self-review before requesting review** — Read your own diff first
6. **Update the branch** — Rebase or merge main before merging if behind

## Self-Review Checklist (Solo Developer)

Even without a team, review your own PR before merging:

- [ ] I've read every line of the diff
- [ ] No debug code, console.logs, or TODO comments left behind
- [ ] No hardcoded values that should be config
- [ ] Error handling is appropriate (not excessive, not missing)
- [ ] No security issues (SQL injection, XSS, exposed secrets)
- [ ] Tests cover the happy path and at least one edge case
- [ ] The PR does ONE thing (not bundled changes)

## Review Outcomes

| Outcome                       | Meaning                         | Next Step                                       |
| ----------------------------- | ------------------------------- | ----------------------------------------------- |
| **Approve**                   | Code is good to go              | Merge the PR                                    |
| **Comment / Request Changes** | Fixable issues found            | Fix on the same branch, push, re-request review |
| **Decline**                   | Approach is fundamentally wrong | Close PR, new branch, new PR                    |

### Approve → Merge

Straightforward. Merge using the project's merge strategy (see below).

### Comment / Request Changes → Fix and Re-push

1. Read all review comments carefully
2. Fix the issues on the **same branch** (don't create a new one)
3. Commit the fixes with a descriptive message: `fix: address PR feedback — extract validation logic`
4. Push to the same branch — the PR updates automatically
5. Reply to each review comment explaining what you changed
6. Re-request review when all feedback is addressed

### Decline → New Approach

When the PR is declined, the approach itself is wrong — not just the details.

1. **Document why**: Add a comment on the declined PR explaining the reason

2. **Close the PR** (don't delete — keep it as history)

3. **Delete the old branch** (remote and local):

   ```bash
   git checkout main && git pull
   git branch -D feat/old-approach
   git push origin --delete feat/old-approach
   ```

4. **Create a new branch** with the revised approach:

   ```bash
   git checkout -b feat/new-approach
   ```

5. **Open a new PR** and reference the declined one:

   ```markdown
   ## Summary
   - Replaces #<declined-PR-number> with a different approach
   - Previous PR was declined because: <reason>

   ## Related
   - Closes #<original-issue>
   - Supersedes #<declined-PR-number>
   ```

6. The **original issue stays open** — only the PR was declined, not the work itself

### Key Point

> A declined PR is not a failure — it's the review process doing its job. The issue remains valid; only the implementation needs rethinking.

## Merge Strategy

- **Squash and merge** for feature branches (clean main history)
- **Merge commit** for large PRs where individual commits tell a story
- **Never rebase and merge** on shared branches (rewrites history)

After merge:

- Delete the feature branch (remote and local)
- Verify the issue was auto-closed
- Check that the board status updated

## Draft PRs

Use Draft PRs when:

- Work is in progress but you want CI feedback
- You want to show the approach before finishing
- You need to save work across machines

Convert to "Ready for review" when done.

## PR Size Guide

| Size   | Lines   | Expectation                                                           |
| ------ | ------- | --------------------------------------------------------------------- |
| Small  | \\< 100 | Quick review, merge fast                                              |
| Medium | 100-400 | Normal review cycle                                                   |
| Large  | 400-800 | Needs justification. Consider splitting.                              |
| XL     | 800+    | Almost always should be split. Exception: generated code, migrations. |

---

# Code Review

> Code review guidelines and reviewer responsibilities.

Source: https://devplaybook.tansuasici.com/docs/process/code-review

## Why Review?

Even solo developers benefit from review. It forces you to:

- Re-read your own code with fresh eyes
- Catch bugs before they reach main
- Maintain consistent quality standards
- Create a decision trail for future reference

## What to Look For

### Correctness

- Does the code do what the PR says it does?
- Are edge cases handled? (null, empty, zero, negative, max values)
- Is the error handling appropriate? (not too much, not too little)
- Does it work for all tenants / roles / locales?

### Security

- User input validated at the boundary?
- No SQL injection, XSS, or path traversal risks?
- Authentication / authorization checks in place?
- No secrets or credentials in the code?
- Multi-tenant isolation preserved? (TenantId filtering)

### Design

- Is this the simplest solution that works?
- Does it follow the project's architecture? (Clean Architecture layers, CQRS, etc.)
- Is the code in the right place? (not business logic in controllers, not DB calls in domain)
- Any unnecessary abstraction or over-engineering?

### Readability

- Can you understand the code without the PR description?
- Are names descriptive? (variables, functions, classes)
- Is the code self-documenting? (comments only where "why" isn't obvious)
- Consistent with the project's conventions?

### Performance (only when relevant)

- N+1 query problems?
- Missing database indexes for new queries?
- Unnecessary memory allocations in hot paths?
- Missing pagination on list endpoints?

### Testing

- Are there tests for the new behavior?
- Do the tests actually verify the right thing? (not just "test exists")
- Are edge cases tested?
- Are the tests readable and maintainable?

## How to Give Feedback

### Comment Types

Use prefixes to clarify intent:

| Prefix          | Meaning                            | Blocks Merge? |
| --------------- | ---------------------------------- | ------------- |
| **blocker:**    | Must fix before merge              | Yes           |
| **suggestion:** | Consider this, but your call       | No            |
| **question:**   | I don't understand this — explain? | Depends       |
| **nit:**        | Trivial style/preference issue     | No            |
| **praise:**     | This is well done                  | No            |

### Examples

```text
blocker: This endpoint has no authorization check. Any authenticated
user can delete any course regardless of role.

suggestion: Consider extracting this validation logic into a shared
validator — CourseValidator already handles similar checks.

question: Why are we caching this for 24 hours? Course data changes
frequently. Is there an invalidation strategy?

nit: This variable could be named `remainingCapacity` instead of `rc`
for clarity.

praise: Clean separation of the query logic here. The projection
approach avoids loading the entire entity — nice.
```

### Rules for Reviewers

1. **Be specific** — "This is wrong" is useless. "This misses the case where courseId is null" is helpful.
2. **Explain why** — Don't just say "change this." Say why it matters.
3. **Suggest alternatives** — If you reject an approach, propose another.
4. **Separate must-fix from nice-to-have** — Use the prefixes above.
5. **Acknowledge good work** — Don't only comment on problems.
6. **Review the PR, not the person** — "This code doesn't handle X" not "You forgot X."
7. **Be timely** — Review within 24 hours. Stale PRs kill momentum.

### Rules for Authors

1. **Don't take it personally** — Review feedback is about the code.
2. **Respond to every comment** — Even if just "Done" or "Agreed, fixed."
3. **Explain your reasoning** — If you disagree, explain why with context.
4. **Keep the PR small** — Large PRs get superficial reviews. Small PRs get thorough ones.
5. **Self-review first** — Read your own diff before anyone else does.

## AI-Assisted Review

When using AI (Claude Code) as a reviewer:

- AI reviews catch: style issues, missing error handling, security patterns, convention violations
- AI reviews miss: business logic correctness, UX implications, performance in context
- **AI review supplements human review — it doesn't replace it**
- Always verify AI suggestions against the project's actual requirements

---

# CI/CD

> Continuous integration and deployment pipelines.

Source: https://devplaybook.tansuasici.com/docs/process/ci-cd

## Core Principle

**CI is the gatekeeper. If CI fails, you don't merge. Period.**

## CI Pipeline Requirements

Every project must have a CI pipeline that runs on:

- Push to `main`
- Pull requests targeting `main`

### Minimum CI Steps by Stack

#### .NET Projects

```yaml
steps:
  - Checkout
  - Setup .NET SDK
  - Restore packages (with cache)
  - Format check (dotnet format --verify-no-changes)
  - Build (dotnet build --no-restore)
  - Unit tests (dotnet test --filter Category!=Integration)
  - Integration tests (with service containers: PostgreSQL, Redis, etc.)
```

#### Next.js Projects

```yaml
steps:
  - Checkout
  - Setup Node.js (with npm cache)
  - Install (npm ci)
  - Lint (npm run lint)
  - Type check (npx tsc --noEmit)
  - Unit tests (npm test -- --run)
  - Build (npm run build)
```

#### Python Projects

```yaml
steps:
  - Checkout
  - Setup Python
  - Install dependencies (pip install -r requirements.txt)
  - Lint (ruff check .)
  - Format check (ruff format --check .)
  - Type check (mypy .)
  - Tests (pytest -v)
```

## CI Rules

1. **Tests MUST block the pipeline** — Never use `continue-on-error: true` or `|| true` on test steps. If tests aren't stable enough to be blocking, fix the tests.
2. **Keep CI fast** — Under 5 minutes for unit tests, under 10 for the full pipeline. Slow CI gets ignored.
3. **Cache dependencies** — Use GitHub Actions cache for NuGet, npm, pip. Saves minutes per run.
4. **Use service containers** — For integration tests, spin up real PostgreSQL/Redis/etc. in CI. Don't mock infrastructure.
5. **Fail fast** — Put linting and formatting first. No point running tests if the code doesn't compile.
6. **Pin versions** — Pin SDK, runtime, and action versions. `actions/checkout@v4`, not `@latest`.
7. **Concurrency control** — Cancel in-progress runs for the same branch. Don't waste compute.

```yaml
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```

## CD Pipeline

### Staging

- Auto-deploy on merge to `main`
- Docker build → push to registry → deploy to staging server
- Run smoke tests after deploy

### Production

- Deploy on version tags (`v*`)
- Same image that passed staging
- Rollback plan documented

### Environment Variables

- Never hardcode secrets in CI files
- Use GitHub Secrets for sensitive values
- Use GitHub Variables for non-sensitive config
- Validate environment variables exist before using them

## Reusable Workflows

For organizations with multiple repos, centralize CI logic:

```yaml
# In the calling repo's .github/workflows/ci.yml
jobs:
  ci:
    uses: <org>/.github/.github/workflows/dotnet-ci.yml@main
    with:
      dotnet-version: '10.0.x'
      project-path: 'src/Api'
    secrets: inherit
```

Benefits:

- Update CI once, all repos get the change
- Consistent standards across projects
- Less copy-paste drift between repos

## GitHub Actions Maintenance

- **Review action versions** quarterly — update `@v4` to `@v5` when available
- **Watch for deprecation warnings** — Node.js runtime updates, action EOL notices
- **Don't duplicate workflows** — One CI per purpose. If two workflows build the same Docker image, consolidate.

---

# Issue Management

> Issue creation, labeling, and triage process.

Source: https://devplaybook.tansuasici.com/docs/process/issues

## Core Rule

**Every piece of work starts with an issue.** No ad-hoc changes, no "quick fixes" without tracking.

## Issue Types

### Feature Request

- Label: `enhancement`
- Template: [templates/issue-feature.md](/docs/templates/issue-feature)
- Must include: context, requirements checklist, acceptance criteria

### Bug Report

- Label: `bug`
- Template: [templates/issue-bug.md](/docs/templates/issue-bug)
- Must include: steps to reproduce, expected vs actual behavior, environment

### Documentation

- Label: `documentation`
- For docs-only changes

## Required Fields

Every issue MUST have:

| Field                   | Why                                                 |
| ----------------------- | --------------------------------------------------- |
| **Title**               | Clear, specific (not "fix bug" or "update feature") |
| **Description/Context** | Why this work matters                               |
| **Checklist**           | Concrete tasks as `- [ ]` items                     |
| **Labels**              | At least one type label + one priority label        |
| **Priority**            | P0/P1/P2/P3 (see below)                             |

## Priority Labels

| Label         | Meaning                                 | Response Time        |
| ------------- | --------------------------------------- | -------------------- |
| `P0-critical` | System down, data loss, security breach | Drop everything      |
| `P1-high`     | Major feature broken, blocking work     | Next working session |
| `P2-medium`   | Important but not blocking              | This sprint/week     |
| `P3-low`      | Nice to have, minor improvement         | When time allows     |

## Domain Labels (Optional but Recommended)

Add area labels to categorize issues by module:

```text
area:auth, area:course, area:analytics, area:ragchat,
area:admin, area:student, area:instructor, area:infra, area:ci
```

## Writing Good Issue Titles

```text
# Bad
Fix bug
Update code
Authentication issue
Doesn't work

# Good
fix: Login redirect fails when callback URL contains query params
feat: Add course enrollment capacity limit
bug: ClickHouse analytics query times out for >10K events
docs: Add deployment guide for Kubernetes setup
```

## Issue Lifecycle

```text
1. Create issue with proper labels and description
2. Add to project board (auto or manual) → lands in "To Do"
3. When starting work → move to "In Progress", assign yourself
4. Create a branch referencing the issue
5. Work, commit, push, open PR with "closes #N"
6. PR merged → issue auto-closes
7. Add a completion comment (what was done, decisions made)
8. Verify issue moved to "Done" on the board
```

## Completion Comment

When closing an issue, add a comment documenting:

```markdown
## Completed

**Changes:**
- Created `AuthService` with JWT + refresh token logic
- Added `POST /api/auth/login` and `POST /api/auth/refresh` endpoints
- Added integration tests for token lifecycle

**Decisions:**
- Used 15-min access token, 7-day refresh (configurable via appsettings)
- Refresh tokens stored in HttpOnly cookies, not localStorage

**Commits:** abc1234, def5678
```

This creates a searchable history of what was done and why.

## Cross-Repo Issues

When work spans multiple repositories:

- Create the issue in the **primary** repo (where most code changes happen)
- Reference other repos in the body: "Also requires changes in `WebApp` repo"
- Link related issues/PRs from other repos in comments

---

# Board Workflow

> Project board columns and card lifecycle.

Source: https://devplaybook.tansuasici.com/docs/process/board-workflow

## Tool: GitHub Projects (Kanban)

Every project has a GitHub Projects board with a standard Kanban layout.

## Columns

```text
To Do → In Progress → Testing → Done
```

| Column          | Meaning                                 | Who Moves Here                |
| --------------- | --------------------------------------- | ----------------------------- |
| **To Do**       | Triaged, prioritized, ready to pick up  | Product/lead during planning  |
| **In Progress** | Actively being worked on                | Developer when starting       |
| **Testing**     | PR open, CI passing, awaiting review/QA | Developer when PR is ready    |
| **Done**        | Merged, deployed, verified              | Auto or developer after merge |

## Rules

1. **Move to In Progress BEFORE writing code** — Not after. This signals ownership.
2. **One In Progress per person** — Focus. Don't juggle 5 issues at once.
3. **In Progress means active work** — If you stop working on it, move it back to To Do.
4. **Testing means PR is ready** — Not "I'll open a PR later." The PR exists and CI is green.
5. **Done means verified** — Not just merged. Confirm it works in the target environment.

## Issue Flow

```text
Issue Created
    ↓
[To Do] — Triaged with priority + labels
    ↓
[In Progress] — Developer picks it up, creates branch
    ↓
[Testing] — PR opened with "Closes #N", CI passing
    ↓
[Done] — PR merged, issue closed with completion comment
```

## Board Hygiene

- **Weekly sweep**: Review To Do column, re-prioritize if needed
- **No "No Status" items**: Every issue on the board must be in a column
- **Archive Done items** monthly to keep the board clean
- **If an issue is stale** (no activity for 2+ weeks in To Do): either re-prioritize or close with a reason

## Multi-Repo Projects

When a project spans multiple repos (e.g., API + WebApp):

- Each repo has its own board
- Cross-repo work: create the issue in the primary repo, link to the other
- Sync status manually — if API is done but WebApp isn't, the API issue can be Done while the WebApp issue stays In Progress

## GitHub CLI Quick Reference

```bash
# List project items
gh project item-list <PROJECT_NUMBER> --owner <ORG_OR_USER>

# View specific issue
gh issue view <NUMBER> --repo <ORG>/<REPO>

# Move issue status (requires GraphQL — use the web UI for simplicity)
# Or use gh project item-edit with the field and value IDs
```

---

# Incident Response

> On-call, escalation, and post-mortem procedures.

Source: https://devplaybook.tansuasici.com/docs/process/incident-response

## Severity Levels

| Severity  | Definition                                | Response Time   | Example                                 |
| --------- | ----------------------------------------- | --------------- | --------------------------------------- |
| **SEV-1** | System down, all users affected           | Immediately     | Database crash, main domain unreachable |
| **SEV-2** | Major feature broken, many users affected | Within 1 hour   | Login broken, payments failing          |
| **SEV-3** | Minor feature broken, workaround exists   | Within 24 hours | Export button not working, UI glitch    |
| **SEV-4** | Cosmetic or non-urgent issue              | Next sprint     | Typo on page, alignment off             |

## When Something Breaks

### Step 1: Assess (2 minutes)

- What is broken?
- Who is affected? (all users, one tenant, one role?)
- Is data at risk? (data loss, corruption, leak?)
- What changed recently? (last deploy, config change, infrastructure update?)

### Step 2: Communicate (5 minutes)

- Notify stakeholders that you're aware and investigating
- Set expectations: "Investigating, will update in 30 minutes"
- Don't guess at the cause — say what you know

### Step 3: Mitigate (first priority)

**Stop the bleeding before finding root cause.**

Options (in order of preference):

1. **Rollback**: Deploy the previous known-good version
2. **Feature flag**: Disable the broken feature
3. **Hotfix**: If the fix is obvious and small (\\< 10 lines)
4. **Scale**: If it's a capacity issue, add resources

```bash
# Rollback to previous deployment
docker pull ghcr.io/org/api:previous-tag
docker compose up -d api

# Or revert the last merge
git revert <merge-commit-hash>
# Open PR, get CI green, merge, deploy
```

### Step 4: Fix Root Cause

After the immediate impact is mitigated:

1. Create a GitHub issue labeled `bug` + `P0-critical` or `P1-high`
2. Branch: `hotfix/<description>`
3. Fix, test, PR, review, merge
4. Deploy and verify

### Step 5: Post-Mortem

Write a post-mortem for any SEV-1 or SEV-2 incident. No blame — focus on systems.

## Post-Mortem Template

```markdown
## Incident: <Title>

**Date**: YYYY-MM-DD
**Severity**: SEV-1 / SEV-2
**Duration**: X hours/minutes
**Impact**: <Who was affected and how>

### Timeline

| Time | Event |
|------|-------|
| HH:MM | First alert / user report |
| HH:MM | Investigation started |
| HH:MM | Root cause identified |
| HH:MM | Mitigation applied |
| HH:MM | Confirmed resolved |

### Root Cause

<What actually caused the issue — be specific>

### What Went Well

- <Things that helped resolve the issue faster>

### What Went Wrong

- <Things that made the issue worse or delayed resolution>

### Action Items

- [ ] <Preventive measure 1> — Owner: @who — Due: YYYY-MM-DD
- [ ] <Preventive measure 2> — Owner: @who — Due: YYYY-MM-DD
- [ ] <Monitoring/alerting improvement> — Owner: @who — Due: YYYY-MM-DD
```

## Prevention

- **Monitor**: Set up health checks and alerts before you need them
- **Deploy small**: Small deploys = small blast radius = easy rollback
- **Feature flags**: Gate risky features behind flags
- **Staging first**: Always deploy to staging before production
- **Automated tests**: Catch regressions before they reach production
- **Database backups**: Automated, tested, restorable

---

# Dependency Management

> Package updates, vulnerability scanning, and lockfile policy.

Source: https://devplaybook.tansuasici.com/docs/process/dependency-management

## Core Principle

**Dependencies are liabilities, not assets.** Every dependency you add is code you don't control. Add them deliberately, update them regularly, remove them when unused.

## Adding a Dependency

Before adding a new package, ask:

1. **Do I actually need this?** Can I write 20 lines instead of adding a library?
2. **Is it maintained?** Check: last commit date, open issues, release frequency
3. **Is it widely used?** Downloads/stars matter — more users = more eyes on bugs
4. **License compatible?** MIT, Apache 2.0 = safe. GPL = careful. Commercial = check cost.
5. **How big is it?** Don't add a 2MB library for one utility function

### Red Flags

- No commits in 12+ months
- Many open issues with no maintainer response
- Single maintainer with no succession plan
- Transitive dependency tree is huge
- License changed recently (e.g., AutoMapper went commercial)

## Version Pinning

| Context                | Strategy           | Example                         |
| ---------------------- | ------------------ | ------------------------------- |
| Application (deployed) | Pin exact versions | `"express": "4.18.2"`           |
| Lock files             | Always commit      | `package-lock.json`, `*.csproj` |
| CI/CD actions          | Pin major version  | `actions/checkout@v4`           |
| Docker base images     | Pin specific tag   | `node:22.5-alpine`              |
| Development tools      | Range OK           | `"eslint": "^8.0.0"`            |

## Updating Dependencies

### Schedule

- **Security patches**: Immediately (same day)
- **Patch updates**: Weekly or bi-weekly
- **Minor updates**: Monthly
- **Major updates**: Plan and test — don't rush

### Process

```bash
# Check for outdated packages
npm outdated                    # Node.js
dotnet list package --outdated  # .NET
pip list --outdated             # Python

# Check for vulnerabilities
npm audit                              # Node.js
dotnet list package --vulnerable       # .NET
pip-audit                              # Python
```

1. Update in a dedicated branch: `chore/update-dependencies`
2. Run full test suite after updating
3. Check for breaking changes in changelogs
4. Don't bundle dependency updates with feature work

### Major Version Upgrades

Major upgrades (e.g., Next.js 15 → 16, .NET 9 → 10) are projects, not chores:

1. Read the migration guide
2. Create a GitHub issue tracking the upgrade
3. Do it in a dedicated branch with focused commits
4. Test thoroughly — major versions often have breaking changes
5. Update CI/CD if SDK versions changed

## Security Vulnerabilities

### Automated Scanning

- Enable **Dependabot** or **Renovate** on GitHub repos
- Run `npm audit` / `dotnet list package --vulnerable` in CI
- Don't ignore vulnerability warnings — they don't go away

### Response

| Severity      | Action                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------- |
| Critical/High | Update within 24 hours. If no fix available, evaluate workaround or alternative package. |
| Medium        | Update within 1 week                                                                     |
| Low           | Update in next regular maintenance cycle                                                 |

## Removing Dependencies

Unused dependencies are dead weight:

- Increase build time
- Expand attack surface
- Create confusion ("why is this here?")

Periodically audit:

```bash
# Find unused packages (Node.js)
npx depcheck

# .NET — check for unused package references manually or with IDE tools
```

If a package is unused, remove it. Don't leave it "just in case."

---

# New Project Setup

> Checklist for bootstrapping a new project.

Source: https://devplaybook.tansuasici.com/docs/checklists/new-project-setup

Run through this when starting any new project.

## Repository Setup

- [ ] Create GitHub repo (org or personal)
- [ ] Clone locally
- [ ] Add `.gitignore` (use GitHub's template for your language)
- [ ] Create `CLAUDE.md` from [templates/claude-md-starter.md](/docs/templates/claude-md-starter)
- [ ] Create `README.md` with project overview and setup instructions

## GitHub Configuration

- [ ] Create GitHub Project board (Kanban: To Do → In Progress → Testing → Done)

- [ ] Add labels to repo (see [labels.yml](https://github.com/tansuasici/dev-playbook/blob/main/labels.yml)):

  ```bash
  # Priority labels
  gh label create "P0-critical" --color "B60205" --description "Critical priority" --repo <repo>
  gh label create "P1-high" --color "D93F0B" --description "High priority" --repo <repo>
  gh label create "P2-medium" --color "FBCA04" --description "Medium priority" --repo <repo>
  gh label create "P3-low" --color "0E8A16" --description "Low priority" --repo <repo>
  ```

- [ ] Add PR template: `.github/PULL_REQUEST_TEMPLATE.md` (from [templates/pull-request.md](/docs/templates/pull-request))

- [ ] Add issue templates: `.github/ISSUE_TEMPLATE/` (from [templates/](https://github.com/tansuasici/dev-playbook/tree/main/templates))

- [ ] Enable branch protection on `main` (if on paid plan):
  - Require PR before merging
  - Require CI status checks to pass
  - Do not allow force pushes

## CI/CD

- [ ] Create `.github/workflows/ci.yml` (follow [process/ci-cd.md](/docs/process/ci-cd))
- [ ] Verify CI runs on push and PR
- [ ] Ensure tests block the pipeline (no `continue-on-error`)
- [ ] Add GitHub Secrets for any required environment variables

## Development Environment

- [ ] `docker-compose.yml` for local services (DB, cache, etc.)
- [ ] `.env.example` with all required env vars (no real values)
- [ ] Verify: `git clone` → install → run → tests pass (fresh machine test)
- [ ] Document setup steps in README or CLAUDE.md

## Code Quality

- [ ] Linter configured and running in CI
- [ ] Formatter configured (or format check in CI)
- [ ] Type checking enabled (TypeScript strict, mypy, etc.)
- [ ] Pre-commit hooks (optional but recommended): lint + format on commit

## First Issue

- [ ] Create the first issue on the board (project scaffold or first feature)
- [ ] Assign priority label
- [ ] Add to the project board
- [ ] Start working using the branch → PR → merge flow from day one

---

# Developer Onboarding

> New team member onboarding checklist.

Source: https://devplaybook.tansuasici.com/docs/checklists/onboarding

What to do on your first day with a project (or when onboarding someone new).

## Access & Accounts

- [ ] GitHub organization/repo access granted
- [ ] Added to the project board(s)
- [ ] Access to deployment environments (staging, production)
- [ ] Access to monitoring/logging tools (Seq, Grafana, etc.)
- [ ] Access to communication channels (Slack, Discord, etc.)
- [ ] Secrets/credentials shared securely (never via chat or email)

## Local Environment

- [ ] Clone the repository
- [ ] Read the `README.md` and `CLAUDE.md`
- [ ] Read the [dev-playbook](https://github.com/tansuasici/dev-playbook) — especially `process/` and `conventions/`
- [ ] Install required runtimes and tools:
  - [ ] .NET SDK (check version in `global.json`)
  - [ ] Node.js (check version in `.nvmrc` or `package.json`)
  - [ ] Python (check version in `pyproject.toml`)
  - [ ] Docker Desktop
- [ ] Copy `.env.example` to `.env` and fill in values
- [ ] Start infrastructure: `docker compose up -d`
- [ ] Install dependencies: `dotnet restore` / `npm ci` / `pip install`
- [ ] Run the app locally and verify it starts
- [ ] Run the tests and verify they pass
- [ ] Install git hooks (see [conventions/git-hooks.md](/docs/conventions/git-hooks))

## Understand the Project

- [ ] Read the architecture docs in the playbook (`architecture/`)
- [ ] Understand the project structure (where code lives, how layers connect)
- [ ] Review the project board — what's in progress, what's coming
- [ ] Read the last 10 commit messages to understand recent work
- [ ] Read 2-3 recent closed PRs to understand the review process

## First Contribution

- [ ] Pick a small issue from the board (labeled `good first issue` if available)
- [ ] Follow the full workflow:
  1. Move issue to "In Progress"
  2. Create a feature branch
  3. Make the change
  4. Write tests
  5. Open a PR with proper template
  6. Get review, address feedback
  7. Merge and close the issue

## Knowledge Gaps

Don't be afraid to ask. Document answers for the next person:

- [ ] I understand the authentication flow
- [ ] I understand how multi-tenancy works (if applicable)
- [ ] I know how to deploy to staging
- [ ] I know where to find logs when something breaks
- [ ] I know who to ask when I'm stuck

---

# Pre-Merge Checklist

> Things to verify before merging a PR.

Source: https://devplaybook.tansuasici.com/docs/checklists/pre-merge

Review before merging any PR to `main`.

## Code Quality

- [ ] CI pipeline is green (all checks pass)
- [ ] No linting warnings or errors
- [ ] No type errors
- [ ] Code compiles/builds without warnings

## Self-Review

- [ ] I've read every line of the diff in the PR
- [ ] No debug code left (console.log, print, debugger, TODO/FIXME)
- [ ] No hardcoded values that should be environment variables
- [ ] No commented-out code blocks
- [ ] Variable and function names are clear and descriptive

## Testing

- [ ] Unit tests added for new logic
- [ ] Existing tests still pass
- [ ] Edge cases considered (null, empty, boundary values)
- [ ] Manual testing done for UI changes

## Security

- [ ] No secrets or credentials in the code
- [ ] User input is validated at the boundary
- [ ] No SQL injection risk (parameterized queries)
- [ ] No XSS risk (output is sanitized/escaped)
- [ ] Authentication/authorization checks in place for new endpoints
- [ ] Multi-tenant: TenantId filter applied on all data queries

## API Changes (if applicable)

- [ ] Backward compatible (or breaking change is documented)
- [ ] Request/response DTOs validated
- [ ] Error responses are consistent and informative
- [ ] OpenAPI/Swagger docs updated

## Database Changes (if applicable)

- [ ] Migration created and tested
- [ ] Migration is reversible (down migration works)
- [ ] New columns have appropriate defaults or are nullable
- [ ] Indexes added for frequently queried columns
- [ ] TenantId included on new tables

## PR Metadata

- [ ] PR references the issue (`Closes #N`)
- [ ] PR title follows Conventional Commits format
- [ ] PR description has Summary, Changes, and Test Plan sections
- [ ] PR is focused on ONE concern (not bundled changes)

---

# Release Checklist

> Release preparation and deployment steps.

Source: https://devplaybook.tansuasici.com/docs/checklists/release

Run through this before tagging a release.

## Pre-Release

- [ ] All planned issues for this release are Done on the board
- [ ] No open P0 or P1 bugs
- [ ] All CI pipelines are green on `main`
- [ ] Manual smoke test on staging environment
- [ ] Database migrations applied and verified on staging

## Versioning

Use [Semantic Versioning](https://semver.org/):

```text
v<MAJOR>.<MINOR>.<PATCH>

MAJOR — Breaking changes (incompatible API changes)
MINOR — New features (backward compatible)
PATCH — Bug fixes (backward compatible)
```

- [ ] Version number determined based on changes since last release
- [ ] CHANGELOG or release notes drafted

## Tag and Release

```bash
# Create annotated tag
git tag -a v1.2.0 -m "Release v1.2.0: <summary>"

# Push tag
git push origin v1.2.0

# Create GitHub release
gh release create v1.2.0 --title "v1.2.0" --notes "$(cat <<'EOF'
## What's New
- feat: Added course enrollment capacity (#42)
- feat: Added analytics dashboard (#45)

## Bug Fixes
- fix: Login redirect with query params (#48)

## Breaking Changes
- None
EOF
)"
```

## Post-Release

- [ ] Verify deployment succeeded (check logs, health endpoint)
- [ ] Smoke test production (critical user flows)
- [ ] Monitor error rates for 30 minutes after deploy
- [ ] Close the milestone (if using milestones)
- [ ] Announce release to stakeholders (if applicable)

## Rollback Plan

If something goes wrong:

1. **Revert the deploy**: Redeploy the previous version (previous Docker image tag)
2. **Don't panic**: Check logs first, understand the failure
3. **Hotfix if small**: If the fix is obvious and small, branch `hotfix/...`, fix, PR, merge, redeploy
4. **Revert if complex**: `git revert <merge-commit>`, PR, merge, redeploy
5. **Post-mortem**: Document what went wrong and how to prevent it

---

# Security Audit

> Periodic security review checklist.

Source: https://devplaybook.tansuasici.com/docs/checklists/security-audit

Run this checklist periodically (quarterly) or before major releases.

## Authentication & Authorization

- [ ] Passwords hashed with bcrypt/Argon2 (not MD5/SHA)
- [ ] Access tokens are short-lived (\\< 30 minutes)
- [ ] Refresh tokens stored in HttpOnly cookies
- [ ] Failed login attempts are rate-limited
- [ ] Session tokens invalidated on logout
- [ ] Role/permission checks on every protected endpoint
- [ ] No privilege escalation paths (user can't elevate to admin)
- [ ] Token refresh endpoint validates the refresh token properly

## Input Validation

- [ ] All user input validated at the API boundary
- [ ] No raw SQL concatenation (parameterized queries only)
- [ ] File uploads validated: MIME type, extension, size limit
- [ ] No path traversal possible via user input
- [ ] HTML output sanitized to prevent XSS
- [ ] JSON parsing rejects unexpected fields (strict deserialization)
- [ ] Query parameters validated (pagination limits, sort fields)

## Data Protection

- [ ] Sensitive data encrypted at rest (database encryption)
- [ ] TLS/HTTPS enforced on all endpoints
- [ ] No secrets in source code or git history
- [ ] `.env` files in `.gitignore`
- [ ] API keys and credentials stored in secrets manager
- [ ] Personal data deletable (GDPR right to erasure)
- [ ] Logs don't contain passwords, tokens, or PII
- [ ] Database backups encrypted

## API Security

- [ ] CORS restricted to known origins (no wildcard in production)
- [ ] Rate limiting enabled on all endpoints
- [ ] Security headers set (X-Content-Type-Options, X-Frame-Options, HSTS, CSP)
- [ ] Error responses don't leak internal details (no stack traces)
- [ ] API versioning doesn't expose deprecated/vulnerable endpoints
- [ ] Request size limits configured (prevent large payload attacks)

## Multi-Tenancy (if applicable)

- [ ] Every database query filters by TenantId
- [ ] Global query filters active and tested
- [ ] Cross-tenant data access is impossible via API
- [ ] Cache keys are tenant-scoped
- [ ] File storage is tenant-isolated
- [ ] Admin endpoints are properly restricted

## Dependencies

- [ ] No known vulnerabilities in dependencies (`npm audit`, `dotnet list package --vulnerable`)
- [ ] Dependencies are up to date (no EOL frameworks/runtimes)
- [ ] Lock files committed and reviewed
- [ ] No unnecessary dependencies (attack surface reduction)

## Infrastructure

- [ ] Database not publicly accessible (firewall rules)
- [ ] SSH keys rotated (no shared keys)
- [ ] Docker containers run as non-root
- [ ] Unused ports closed
- [ ] Health check endpoints don't leak system info
- [ ] Monitoring alerts configured for anomalies

## Code Review

- [ ] Security-sensitive changes reviewed by someone else (or thorough self-review)
- [ ] No hardcoded credentials found (`grep -r "password\|secret\|api_key"`)
- [ ] No TODO/FIXME items related to security

---

# CLAUDE.md Starter

> Template for creating CLAUDE.md files.

Source: https://devplaybook.tansuasici.com/docs/templates/claude-md-starter

Copy this to the root of a new project and customize.

---

````markdown
# <Project Name> — CLAUDE.md

> <One-line description of the project>

---

## Development Process

Follow the playbook at https://github.com/tansuasici/dev-playbook
Read all files under `process/` and `conventions/` before starting work.

---

## Project Context

<!-- What is this project? Who uses it? What problem does it solve? -->

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | |
| Frontend | |
| Database | |
| Cache | |
| CI/CD | |

---

## Getting Started

```bash
# Clone
git clone <repo-url>
cd <project>

# Install dependencies
<commands>

# Run locally
<commands>

# Run tests
<commands>
```

---

## Project Structure

```
<project>/
├── src/
│   └── ...
├── tests/
│   └── ...
└── ...
```

---

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DATABASE_URL` | PostgreSQL connection string | Yes |
| `REDIS_URL` | Redis connection string | No (defaults to localhost) |

---

## Code Conventions

Follow `conventions/` in the dev-playbook. Project-specific overrides:

- <!-- Any project-specific rules that override or extend the playbook -->

---

## Task Management

<!-- GitHub Projects board URL -->
<!-- Kanban workflow: To Do → In Progress → Testing → Done -->

---

## Infrastructure

| Service | Port | Purpose |
|---------|------|---------|
| | | |

---

## Key Decisions

<!-- Link to ADRs or document project-specific architectural decisions here -->
````

---

# Bug Report Template

> GitHub issue template for bug reports.

Source: https://devplaybook.tansuasici.com/docs/templates/issue-bug

Copy this when reporting a bug on GitHub.

---

**Title**: `bug: <short description of the problem>`

**Labels**: `bug`, `P1-high` (adjust priority)

**Body**:

```markdown
## Bug Description

<!-- Clear, concise description of what's wrong -->

## Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. Enter '...'
4. See error

## Expected Behavior

<!-- What should happen -->

## Actual Behavior

<!-- What actually happens. Include error messages, screenshots, logs if available. -->

## Environment

- **Browser/Client**: Chrome 120 / Safari 18 / API client
- **OS**: macOS / Windows / Linux
- **Deployed version**: commit hash or tag
- **Tenant**: (if multi-tenant)

## Possible Cause

<!-- Optional: If you have a theory about what's causing this -->

## Workaround

<!-- Optional: Is there a temporary workaround? -->
```

---

## GitHub CLI Example

```bash
gh issue create \
  --repo <org>/<repo> \
  --title "bug: login redirect fails with query params in callback URL" \
  --label "bug,P1-high" \
  --body "$(cat <<'EOF'
## Bug Description

When a user is redirected to login from a page with query parameters, the callback URL is truncated after the `?`, causing a 404 after successful login.

## Steps to Reproduce

1. Visit `/courses?filter=active&sort=date` while logged out
2. Get redirected to `/login?callbackUrl=/courses?filter=active&sort=date`
3. Login successfully
4. Redirected to `/courses?filter=active` (truncated)

## Expected Behavior

Redirect to the full original URL including all query parameters.

## Actual Behavior

URL is truncated at the second `?`. Only the first query parameter is preserved.

## Environment

- Browser: Chrome 120
- OS: macOS 15
- Version: commit abc1234

## Possible Cause

The callback URL is not being URL-encoded before being added as a query parameter.
EOF
)"
```

---

# Feature Request Template

> GitHub issue template for feature requests.

Source: https://devplaybook.tansuasici.com/docs/templates/issue-feature

Copy this when creating a feature issue on GitHub.

---

**Title**: `feat: <short description>`

**Labels**: `enhancement`, `P1-high` (adjust priority)

**Body**:

```markdown
## Context

<!-- Why is this needed? What problem does it solve? -->

## Requirements

- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Acceptance Criteria

<!-- How do we know this is done? -->

- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Tests written and passing

## Technical Notes

<!-- Optional: implementation hints, API contracts, related issues -->

## Out of Scope

<!-- What this issue does NOT cover -->
```

---

## GitHub CLI Example

```bash
gh issue create \
  --repo <org>/<repo> \
  --title "feat: add course enrollment capacity limit" \
  --label "enhancement,P1-high" \
  --body "$(cat <<'EOF'
## Context

Instructors need to limit how many students can enroll in a course.

## Requirements

- [ ] Add `MaxCapacity` field to Course entity
- [ ] Validate enrollment count before allowing new enrollment
- [ ] Show remaining capacity on course detail page
- [ ] Return 409 Conflict when course is full

## Acceptance Criteria

- [ ] Enrollment fails gracefully when course is at capacity
- [ ] Capacity is displayed in the UI
- [ ] Unit tests for enrollment validation
- [ ] Integration test for the enrollment endpoint

## Technical Notes

- Requires migration to add `MaxCapacity` column
- Default value: null (unlimited)
EOF
)"
```

---

# Pull Request Template

> PR description template.

Source: https://devplaybook.tansuasici.com/docs/templates/pull-request

Copy this into `.github/PULL_REQUEST_TEMPLATE.md` in each repo, or use it manually.

---

```markdown
## Summary

- <!-- What does this PR do and why? 1-3 bullet points -->

## Changes

- <!-- List significant changes. Not a file-by-file diff, but what matters. -->

## Test Plan

- [ ] Unit tests added/updated
- [ ] Manual testing completed
- [ ] Edge cases considered
- [ ] CI passes

## Self-Review Checklist

- [ ] I've read every line of the diff
- [ ] No debug code or console.logs left behind
- [ ] No hardcoded values that should be config
- [ ] No security issues (injection, exposed secrets, missing auth)
- [ ] Error handling is appropriate
- [ ] This PR does ONE thing

## Related

- Closes #<!-- issue number -->

---
Generated with [Claude Code](https://claude.com/claude-code)
```

---

## Usage

### Option A: Auto-populate for all PRs

Save the content between the \`\`\` fences as `.github/PULL_REQUEST_TEMPLATE.md` in your repo. GitHub will auto-fill this template every time someone opens a PR.

### Option B: Use with gh CLI

```bash
gh pr create \
  --title "feat: add course enrollment limit" \
  --body "$(cat <<'EOF'
## Summary

- Add MaxCapacity field to courses with enrollment validation

## Changes

- Added `MaxCapacity` column to Course entity + migration
- Enrollment endpoint now returns 409 when course is full
- Course detail page shows remaining spots

## Test Plan

- [x] Unit tests for EnrollStudentCommandHandler capacity check
- [x] Integration test for 409 response
- [x] Manual testing with capacity = 1, 0, null (unlimited)

## Self-Review Checklist

- [x] Read the diff
- [x] No debug code
- [x] No hardcoded values
- [x] No security issues
- [x] Error handling appropriate
- [x] Single concern

## Related

- Closes #42

---
Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
```

---

# Changelog

> All notable changes to Dev Playbook.

Source: https://devplaybook.tansuasici.com/docs/changelog

All notable changes to this playbook will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).

## [1.1.1](https://github.com/tansuasici/dev-playbook/compare/v1.1.0...v1.1.1) (2026-04-07)

### Bug Fixes

- exclude CHANGELOG.md from markdownlint CI ([97214e4](https://github.com/tansuasici/dev-playbook/commit/97214e497ffb2fc2c0bd948369f620f583b67b66))

## [1.1.0](https://github.com/tansuasici/dev-playbook/compare/v1.0.0...v1.1.0) (2026-04-07)

### Features

- add 12 new guides — code review, API design, testing, logging, docker, incidents, and more ([bd43392](https://github.com/tansuasici/dev-playbook/commit/bd43392e7cb9007b6f9223e1f0a039e63b328218))
- add open-source infrastructure and 7 new convention guides ([c739cfc](https://github.com/tansuasici/dev-playbook/commit/c739cfc65e229dfd5fb8314823c5c05e7734d9da))
- add PR review outcomes flow (approve, comment, decline) ([71fc964](https://github.com/tansuasici/dev-playbook/commit/71fc96428ee47b7ab50cb484ad9d242fb8584102))
- initialize dev-playbook with full development standards ([11adf4b](https://github.com/tansuasici/dev-playbook/commit/11adf4ba49dd4eba9d834fc9621e4ddeddfc7775))

### Bug Fixes

- correct relative path to CONTRIBUTING.md in PR template ([a1a1f72](https://github.com/tansuasici/dev-playbook/commit/a1a1f72e681015f6529c8682082e599b1dd10973))
- replace angle-bracket URL with plain text for MDX compatibility ([8791153](https://github.com/tansuasici/dev-playbook/commit/87911530f9dc43d1bd8b44f9d5681c9696eb2f52))
- resolve 145 markdownlint errors across all docs ([5e4d5a4](https://github.com/tansuasici/dev-playbook/commit/5e4d5a47f06baeba5add68581f2bccd4ab00eb96))
- resolve broken links and lint errors from review feedback ([0a6343a](https://github.com/tansuasici/dev-playbook/commit/0a6343a17a5f4dd7b7a8c31fe79ee340ef14724b))

## \[1.0.0] - 2025-03-16

### Added

- **Process guides**: branching, commits, issues, pull requests, code review, CI/CD, board workflow, incident response, dependency management
- **Convention guides**: .NET, Next.js, Python, naming, API design, API error format, testing, logging, Docker, git hooks, observability, environment management, documentation, error handling, performance, accessibility, i18n
- **Architecture guides**: ADR, database, security, multi-tenancy
- **Checklists**: new project setup, onboarding, pre-merge, release, security audit
- **Templates**: feature issue, bug issue, PR template, CLAUDE.md starter
- **Open-source infrastructure**: LICENSE (MIT), CONTRIBUTING.md, CODE\_OF\_CONDUCT.md
- **GitHub integration**: issue templates (YAML), PR template, CI workflow (markdown lint + link check)
- **Standard label set**: labels.yml with type, priority, status categories

---