Technical Documentation Generator

# My Project — Technical Documentation

## Overview

My Project is built with Next.js, TypeScript, PostgreSQL, Tailwind CSS. This document provides technical reference for engineers working on or integrating with the project.

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Installation](#installation)
4. [Configuration](#configuration)
5. [API Reference](#api-reference)
6. [Data Models](#data-models)
7. [Security](#security)
8. [Contributing](#contributing)

---

## Architecture

### System Diagram

```
Client (Browser / Mobile)
         │
         ▼
  [Next.js App Router]  ─── Server Components (RSC)
         │
         ▼
  [API Routes / Server Actions]
         │
         ▼
  [Database Layer]  ──────  PostgreSQL (Neon)
```

### Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| App Router | Enables server-side rendering, RSC, and streaming |
| Server Components | Reduces client bundle, improves TTFB |
| Drizzle ORM | Type-safe queries, lightweight, close to SQL |
| Better Auth | Production-ready session management, no OAuth boilerplate |

---

## Installation

```bash
git clone https://github.com/your-org/my-project
cd my-project
pnpm install
cp .env.example .env.local
pnpm db:migrate
pnpm dev
```

---

## Configuration

All configuration is managed via environment variables. See `.env.example` for the complete list.

| Variable | Required | Description |
|----------|----------|-------------|
| DATABASE_URL | Yes | PostgreSQL connection string |
| BETTER_AUTH_SECRET | Yes | 32-byte session signing secret |
| NEXT_PUBLIC_APP_URL | Yes | Public base URL |
| ADMIN_EMAIL | Yes | Initial admin account email |

---

## API Reference

All API routes are under `/api`. Authentication uses Bearer tokens or session cookies.

### Response Format

```typescript
type ApiResponse<T> = {
  data: T
  error?: { code: string; message: string }
}
```

### Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Validation error |
| 401 | Unauthenticated |
| 403 | Forbidden |
| 500 | Server error |

---

## Data Models

### User

```typescript
interface User {
  id: string
  email: string
  name: string
  role: 'user' | 'admin'
  createdAt: Date
  updatedAt: Date
}
```

### Session

```typescript
interface Session {
  id: string
  userId: string
  token: string
  expiresAt: Date
  ipAddress?: string
  userAgent?: string
}
```

---

## Security

- **Authentication**: Better Auth with httpOnly session cookies
- **SQL Injection**: All queries use parameterized statements via Drizzle ORM
- **CSRF**: Mitigated by SameSite cookie policy and origin validation
- **Input Validation**: Server-side validation on all API routes
- **Secrets**: Never committed to version control; loaded via environment variables
- **HTTPS**: Required in production; enforced via middleware

---

## Contributing

1. Fork and clone the repository
2. Install dependencies: `pnpm install`
3. Create a feature branch: `git checkout -b feature/description`
4. Write tests for new functionality
5. Submit a pull request with a clear description

### Commit Convention

Follow [Conventional Commits](https://conventionalcommits.org):

```
feat: add user profile page
fix: resolve session expiry edge case
docs: update API reference
refactor: extract auth utilities
```

---

*My Project Technical Documentation — Last updated July 2026*