Full-Stack API Design Document Generator

You are a senior software architect. Generate a comprehensive API design document for the following project:

- **Project name**: [project name]
- **Description**: [what this API does]
- **Tech stack**: [e.g., Node.js + Express + PostgreSQL / Python + FastAPI + MongoDB]
- **Authentication**: [JWT / OAuth2 / API Key / Session-based]
- **API style**: [REST / GraphQL / gRPC]
- **Primary consumers**: [web app / mobile app / third-party integrations / internal services]

---

- High-level architecture diagram (describe in text)
- Base URL structure and versioning strategy
- Request/response format (JSON, content types)
- Pagination strategy (cursor vs offset, default page size)
- Filtering and sorting conventions
- HATEOAS or linking strategy (if applicable)

- Auth flow diagram (step-by-step)
- Token format and lifetime
- Refresh token strategy
- Role-based access control (RBAC) matrix
- API key management for service-to-service
- Rate limiting per auth tier (anonymous, authenticated, admin)

For each core entity:
- Entity name and description
- Field definitions with types, constraints, defaults
- Relationships (1:1, 1:N, N:M)
- Indexes and unique constraints
- Soft delete strategy
- Audit fields (createdAt, updatedAt, createdBy)

Define these entities: [entity 1, entity 2, entity 3, ...]

For each endpoint, provide:
- HTTP method + path
- Description
- Auth required (yes/no) + required role
- Request headers
- Path parameters + query parameters (with types and validation)
- Request body schema (with examples)
- Response schema (success + error, with examples)
- Status codes used
- Rate limit tier

Group endpoints by resource:
- CRUD for each entity
- Search/filter endpoints
- Bulk operations
- Aggregate/stats endpoints

- Standard error response format
- Error code registry (map of code → message → HTTP status)
- Validation error format (field-level)
- Business logic error patterns
- Rate limit exceeded response
- Authentication/authorization error responses

- Event types and payloads
- Webhook registration endpoint
- Retry policy and backoff strategy
- Signature verification
- Event ordering guarantees

- Caching strategy (what to cache, TTLs, invalidation)
- Database query optimization notes
- Connection pooling configuration
- Horizontal scaling considerations
- CDN and static asset strategy

Generate a valid OpenAPI 3.0 YAML snippet for the top 5 most important endpoints, including:
- Schemas
- Security definitions
- Example requests and responses

---

- Use tables for data model fields and endpoint summaries
- Include code blocks for request/response examples (JSON)
- Use consistent naming conventions (camelCase for JSON, kebab-case for URLs)
- Mark optional vs required fields clearly
- Total length: 2,000-4,000 words