# Backend Development Guidelines Index

> **Tech Stack**: Next.js 15 API Routes + oRPC + Drizzle ORM + PostgreSQL

## Related Guidelines

| Guideline                 | Location     | When to Read                 |
| ------------------------- | ------------ | ---------------------------- |
| **Shared Code Standards** | `../shared/` | Always - applies to all code |

---

## Documentation Files

| File                                                 | Description                                        | When to Read                       |
| ---------------------------------------------------- | -------------------------------------------------- | ---------------------------------- |
| [directory-structure.md](./directory-structure.md)   | Module organization and directory layout           | Starting a new feature             |
| [orpc-usage.md](./orpc-usage.md)                     | oRPC router, procedures, middleware patterns       | Creating/modifying API endpoints   |
| [type-safety.md](./type-safety.md)                   | Zod schemas, type narrowing, response patterns     | Type-related decisions             |
| [database.md](./database.md)                         | Drizzle ORM, queries, transactions, SQL patterns   | Database operations                |
| [authentication.md](./authentication.md)             | better-auth, sessions, OAuth, protected procedures | Auth-related features              |
| [logging.md](./logging.md)                           | Structured logging, Sentry tracing, telemetry      | Debugging, observability           |
| [local-json-mvp.md](./local-json-mvp.md)             | Local JSON persistence/session/API contracts before database adoption | Single-repo MVP features without DB/oRPC deps |
| [performance.md](./performance.md)                   | Concurrency, caching, batch processing, streaming  | Performance optimization           |
| [ai-sdk-integration.md](./ai-sdk-integration.md)     | Vercel AI SDK, tool calling, prompt patterns       | AI-powered features                |
| [quality.md](./quality.md)                           | Pre-commit checklist for backend code              | Before committing                  |

---

## Quick Navigation

### Service Module Structure

| Task                          | File                                               |
| ----------------------------- | -------------------------------------------------- |
| Project structure             | [directory-structure.md](./directory-structure.md) |
| Domain module pattern         | [directory-structure.md](./directory-structure.md) |
| Write types.ts                | [directory-structure.md](./directory-structure.md) |
| Write procedure               | [directory-structure.md](./directory-structure.md) |
| Write lib/ helpers            | [directory-structure.md](./directory-structure.md) |
| Router setup                  | [orpc-usage.md](./orpc-usage.md)                   |
| Middleware composition        | [orpc-usage.md](./orpc-usage.md)                   |
| Naming conventions            | [directory-structure.md](./directory-structure.md) |

### Type Safety

| Task                 | File                               |
| -------------------- | ---------------------------------- |
| Type safety patterns | [type-safety.md](./type-safety.md) |
| Discriminated unions | [type-safety.md](./type-safety.md) |
| Zod-first types      | [type-safety.md](./type-safety.md) |
| Zod error handling   | [type-safety.md](./type-safety.md) |
| Standard response    | [type-safety.md](./type-safety.md) |

### Database (Drizzle + PostgreSQL)

| Task                    | File                         |
| ----------------------- | ---------------------------- |
| Query organization      | [database.md](./database.md) |
| Batch queries (inArray) | [database.md](./database.md) |
| Conflict handling       | [database.md](./database.md) |
| Transactions            | [database.md](./database.md) |
| JSON column operations  | [database.md](./database.md) |
| Raw SQL camelCase       | [database.md](./database.md) |
| Enum comparison         | [database.md](./database.md) |

### Error Handling / Logging

| Task                        | File                           |
| --------------------------- | ------------------------------ |
| Structured logging          | [logging.md](./logging.md)     |
| Sentry span tracing         | [logging.md](./logging.md)     |
| Error capture               | [logging.md](./logging.md)     |
| oRPC error codes            | [orpc-usage.md](./orpc-usage.md) |
| Batch operation logging     | [logging.md](./logging.md)     |

### Performance

| Task                          | File                               |
| ----------------------------- | ---------------------------------- |
| Parallel execution            | [performance.md](./performance.md) |
| Concurrency control (p-limit) | [performance.md](./performance.md) |
| Exponential backoff retry     | [performance.md](./performance.md) |
| Redis caching                 | [performance.md](./performance.md) |
| Distributed locks             | [performance.md](./performance.md) |
| Chunked batch processing      | [performance.md](./performance.md) |
| Streaming large datasets      | [performance.md](./performance.md) |

### Authentication

| Task                        | File                                   |
| --------------------------- | -------------------------------------- |
| Protected procedures        | [authentication.md](./authentication.md) |
| Admin procedures            | [authentication.md](./authentication.md) |
| Session caching (Redis)     | [authentication.md](./authentication.md) |
| OAuth integration           | [authentication.md](./authentication.md) |
| Role-based access control   | [authentication.md](./authentication.md) |
| Client-side auth            | [authentication.md](./authentication.md) |

### AI Integration

| Task                        | File                                           |
| --------------------------- | ---------------------------------------------- |
| generateText / generateObject | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| Streaming (streamText)      | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| Tool calling                | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| Telemetry configuration     | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| Prompt engineering          | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| AI error handling           | [ai-sdk-integration.md](./ai-sdk-integration.md) |

---

## Core Rules Summary

| Rule                                                             | Reference                                          |
| ---------------------------------------------------------------- | -------------------------------------------------- |
| **No `await` in loops** - use `inArray` for batch queries        | [database.md](./database.md)                       |
| **No `console.log`** - use structured logger                     | [logging.md](./logging.md)                         |
| **No non-null assertions `!`** - use type narrowing              | [type-safety.md](./type-safety.md)                 |
| **All API inputs/outputs have Zod schemas**                      | [type-safety.md](./type-safety.md)                 |
| **Import enums from utils** - not from database package          | [type-safety.md](./type-safety.md)                 |
| **Standard response format** - always include `success`/`reason` | [type-safety.md](./type-safety.md)                 |
| **Use `protectedProcedure`** for authenticated endpoints         | [authentication.md](./authentication.md)           |
| **One procedure per file** - keep procedures focused             | [orpc-usage.md](./orpc-usage.md)                   |
| **Service modules follow domain layout**                         | [directory-structure.md](./directory-structure.md) |
| **Use `Promise.all`** for independent parallel operations        | [performance.md](./performance.md)                 |
| **Use `p-limit`** for external API concurrency control           | [performance.md](./performance.md)                 |
| **Always enable AI telemetry** for token tracking                | [ai-sdk-integration.md](./ai-sdk-integration.md)   |
| **Cast `::jsonb`** for PostgreSQL JSON operations                | [database.md](./database.md)                       |
| **Double-quote camelCase** column names in raw SQL               | [database.md](./database.md)                       |
| **Use structured context** in logs - no string interpolation     | [logging.md](./logging.md)                         |
| **Run pre-commit checklist** before committing                   | [quality.md](./quality.md)                         |

---

## Reference Files

| Feature              | Typical Location                        |
| -------------------- | --------------------------------------- |
| Drizzle Client       | `packages/database/drizzle/client.ts`   |
| Schema Definition    | `packages/database/drizzle/schema/`     |
| Database Queries     | `packages/database/drizzle/queries/`    |
| oRPC Router          | `packages/api/orpc/router.ts`           |
| Base Procedures      | `packages/api/orpc/procedures.ts`       |
| Middleware           | `packages/api/orpc/middleware/`         |
| Service Module       | `packages/api/modules/{domain}/`        |
| Module Types (Zod)   | `packages/api/modules/{domain}/types.ts`|
| Auth Configuration   | `packages/auth/auth.ts`                 |
| Auth Client          | `packages/auth/client.ts`               |
| Shared Utils/Enums   | `packages/utils/`                       |

---

**Language**: All documentation must be written in **English**.