@windagency/valora 2.0.1

package/data/templates/BACKEND_DOC.md

@@ -0,0 +1,241 @@
+# [Document Title]
+
+| Attribute        | Value                       |
+| ---------------- | --------------------------- |
+| **Purpose**      | [Brief purpose description] |
+| **Version**      | 1.0.0                       |
+| **Author**       | AI Documentation Generator  |
+| **Created**      | [YYYY-MM-DD]                |
+| **Last Updated** | [YYYY-MM-DD]                |
+| **Status**       | Draft                       |
+
+---
+
+## Overview
+
+[High-level overview of the document scope and content. Use British English for prose.]
+
+---
+
+## Architecture
+
+[Architecture description with component diagram]
+
+```mermaid
+flowchart TB
+    subgraph API["API Layer"]
+        routes[Routes]
+        middleware[Middleware]
+        controllers[Controllers]
+    end
+
+    subgraph Business["Business Layer"]
+        services[Services]
+        validators[Validators]
+    end
+
+    subgraph Data["Data Layer"]
+        repositories[Repositories]
+        models[Models]
+    end
+
+    routes --> middleware
+    middleware --> controllers
+    controllers --> services
+    services --> validators
+    services --> repositories
+    repositories --> models
+```
+
+---
+
+## [Main Section 1]
+
+[Content for main section]
+
+### [Subsection 1.1]
+
+[Detailed content with code examples using American English for code]
+
+```typescript
+// Example service implementation
+export class ExampleService {
+	constructor(private readonly repository: ExampleRepository) {}
+
+	async findAll(): Promise<Example[]> {
+		return this.repository.findAll();
+	}
+
+	async create(data: CreateExampleDto): Promise<Example> {
+		// Validate input
+		this.validate(data);
+
+		// Create entity
+		return this.repository.create(data);
+	}
+}
+```
+
+### [Subsection 1.2]
+
+[Detailed content]
+
+---
+
+## [Main Section 2]
+
+[Content for section 2]
+
+| Column 1 | Column 2 | Column 3 | Column 4 |
+| -------- | -------- | -------- | -------- |
+| Value 1  | Value 2  | Value 3  | Value 4  |
+
+---
+
+## API Reference
+
+### Endpoint: `[METHOD] /api/v1/[resource]`
+
+**Description**: [Brief description]
+
+**Authentication**: Required / Optional
+
+**Request**:
+
+| Parameter | Location | Type    | Required | Description                 |
+| --------- | -------- | ------- | -------- | --------------------------- |
+| `id`      | path     | string  | Yes      | Resource identifier         |
+| `limit`   | query    | integer | No       | Maximum items (default: 20) |
+
+**Request Body**:
+
+```json
+{
+	"field1": "value1",
+	"field2": 123
+}
+```
+
+**Response** (`200 OK`):
+
+```json
+{
+	"data": {
+		"id": "abc-123",
+		"field1": "value1",
+		"field2": 123,
+		"createdAt": "2025-01-01T00:00:00Z"
+	}
+}
+```
+
+**Error Responses**:
+
+| Status | Code             | Description              |
+| ------ | ---------------- | ------------------------ |
+| 400    | VALIDATION_ERROR | Invalid request data     |
+| 401    | UNAUTHORIZED     | Authentication required  |
+| 403    | FORBIDDEN        | Insufficient permissions |
+| 404    | NOT_FOUND        | Resource not found       |
+| 500    | INTERNAL_ERROR   | Server error             |
+
+---
+
+## Data Model
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : has
+    ENTITY_A {
+        uuid id PK
+        string name
+        timestamp created_at
+    }
+    ENTITY_B {
+        uuid id PK
+        uuid entity_a_id FK
+        string value
+    }
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                       | Symptoms                      | Resolution                                   |
+| --------------------------- | ----------------------------- | -------------------------------------------- |
+| Database connection timeout | `ECONNREFUSED` errors in logs | Check database host/port, verify credentials |
+| Authentication failures     | 401 responses on valid tokens | Check token expiration, verify secret key    |
+| Slow response times         | API latency > 2 seconds       | Check database queries, review N+1 issues    |
+
+### Diagnostic Commands
+
+```bash
+# Check API health
+curl http://localhost:3000/health
+
+# Test database connection
+npm run db:check
+
+# View application logs
+docker logs api-server --tail 100
+
+# Run query analysis
+npm run db:analyze
+```
+
+### Escalation Path
+
+1. Check application logs for stack traces
+2. Verify database connectivity and queries
+3. Check external service dependencies
+4. Contact backend team if issue persists
+
+---
+
+## Best Practices
+
+### Do
+
+- Use dependency injection for testability
+- Implement proper error handling with typed errors
+- Use transactions for multi-step operations
+- Validate all input at API boundaries
+- Write comprehensive unit and integration tests
+
+### Don't
+
+- Expose internal error details to clients
+- Use `any` type in TypeScript
+- Bypass authentication middleware
+- Hardcode configuration values
+- Ignore error handling in async operations
+
+### Checklist
+
+- [ ] All endpoints documented
+- [ ] Error responses standardised
+- [ ] Input validation implemented
+- [ ] Unit tests written (>80% coverage)
+- [ ] Integration tests for critical paths
+
+---
+
+## Related Documentation
+
+| Document                                                | Relationship | Description                |
+| ------------------------------------------------------- | ------------ | -------------------------- |
+| [API.md](./API.md)                                      | Related      | Complete API documentation |
+| [DATA.md](./DATA.md)                                    | Related      | Data model definitions     |
+| [TESTING.md](./TESTING.md)                              | Related      | Testing strategy           |
+| [Frontend ARCHITECTURE.md](../frontend/ARCHITECTURE.md) | See Also     | Frontend integration       |
+
+---
+
+## Changelog
+
+| Version | Date         | Author                     | Changes               |
+| ------- | ------------ | -------------------------- | --------------------- |
+| 1.0.0   | [YYYY-MM-DD] | AI Documentation Generator | Initial documentation |

package/data/templates/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All significant changes to this project will be documented in this file.
+The project format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## <!--
+
+## [x.x.x (latest)](https://[repository]/compare/v[last-version]..v[current-version]) - [release-date]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+-->
+
+---
+
+## [Unreleased](https://[repository]/compare/v[unreleased-version]..HEAD)
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security

package/data/templates/DOC_API_QUICK.md

@@ -0,0 +1,273 @@
+# API Documentation: [Service Name]
+
+| Attribute          | Value                         |
+| ------------------ | ----------------------------- |
+| **Base URL**       | `https://api.example.com/v1`  |
+| **Version**        | 1.0.0                         |
+| **Last Updated**   | [YYYY-MM-DD]                  |
+| **Authentication** | Bearer Token / API Key / None |
+
+---
+
+## Quick Reference
+
+| Method | Endpoint         | Description         | Auth |
+| ------ | ---------------- | ------------------- | ---- |
+| GET    | `/resources`     | List all resources  | Yes  |
+| GET    | `/resources/:id` | Get resource by ID  | Yes  |
+| POST   | `/resources`     | Create new resource | Yes  |
+| PUT    | `/resources/:id` | Update resource     | Yes  |
+| DELETE | `/resources/:id` | Delete resource     | Yes  |
+
+---
+
+## Authentication
+
+### Bearer Token
+
+```bash
+curl -X GET "https://api.example.com/v1/resources" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### API Key
+
+```bash
+curl -X GET "https://api.example.com/v1/resources" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+---
+
+## Endpoints
+
+### GET /resources
+
+List all resources with pagination.
+
+**Query Parameters:**
+
+| Param   | Type    | Default     | Description               |
+| ------- | ------- | ----------- | ------------------------- |
+| `page`  | integer | 1           | Page number               |
+| `limit` | integer | 20          | Items per page (max: 100) |
+| `sort`  | string  | `createdAt` | Sort field                |
+| `order` | string  | `desc`      | Sort order (asc/desc)     |
+
+**Response:**
+
+```json
+{
+	"data": [{ "id": "abc-123", "name": "Resource 1", "createdAt": "2025-01-01T00:00:00Z" }],
+	"pagination": {
+		"page": 1,
+		"limit": 20,
+		"total": 100,
+		"totalPages": 5
+	}
+}
+```
+
+---
+
+### GET /resources/:id
+
+Get a single resource by ID.
+
+**Path Parameters:**
+
+| Param | Type   | Description   |
+| ----- | ------ | ------------- |
+| `id`  | string | Resource UUID |
+
+**Response:**
+
+```json
+{
+	"data": {
+		"id": "abc-123",
+		"name": "Resource 1",
+		"description": "Description here",
+		"createdAt": "2025-01-01T00:00:00Z",
+		"updatedAt": "2025-01-01T00:00:00Z"
+	}
+}
+```
+
+---
+
+### POST /resources
+
+Create a new resource.
+
+**Request Body:**
+
+```json
+{
+	"name": "New Resource",
+	"description": "Optional description"
+}
+```
+
+**Validation Rules:**
+
+| Field         | Rules                    |
+| ------------- | ------------------------ |
+| `name`        | Required, 1-255 chars    |
+| `description` | Optional, max 1000 chars |
+
+**Response:** `201 Created`
+
+```json
+{
+	"data": {
+		"id": "new-uuid",
+		"name": "New Resource",
+		"description": "Optional description",
+		"createdAt": "2025-01-01T00:00:00Z"
+	}
+}
+```
+
+---
+
+### PUT /resources/:id
+
+Update an existing resource.
+
+**Request Body:**
+
+```json
+{
+	"name": "Updated Name",
+	"description": "Updated description"
+}
+```
+
+**Response:** `200 OK`
+
+```json
+{
+	"data": {
+		"id": "abc-123",
+		"name": "Updated Name",
+		"description": "Updated description",
+		"updatedAt": "2025-01-01T12:00:00Z"
+	}
+}
+```
+
+---
+
+### DELETE /resources/:id
+
+Delete a resource.
+
+**Response:** `204 No Content`
+
+---
+
+## Error Responses
+
+All errors follow this format:
+
+```json
+{
+	"error": {
+		"code": "ERROR_CODE",
+		"message": "Human-readable message",
+		"details": {}
+	}
+}
+```
+
+### Error Codes
+
+| HTTP | Code               | Description                 |
+| ---- | ------------------ | --------------------------- |
+| 400  | `VALIDATION_ERROR` | Invalid request body/params |
+| 401  | `UNAUTHORIZED`     | Missing or invalid auth     |
+| 403  | `FORBIDDEN`        | Insufficient permissions    |
+| 404  | `NOT_FOUND`        | Resource not found          |
+| 409  | `CONFLICT`         | Resource already exists     |
+| 422  | `UNPROCESSABLE`    | Business rule violation     |
+| 429  | `RATE_LIMITED`     | Too many requests           |
+| 500  | `INTERNAL_ERROR`   | Server error                |
+
+---
+
+## Rate Limiting
+
+| Tier       | Requests/min | Burst |
+| ---------- | ------------ | ----- |
+| Free       | 60           | 10    |
+| Pro        | 600          | 100   |
+| Enterprise | 6000         | 1000  |
+
+**Rate limit headers:**
+
+```
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1640995200
+```
+
+---
+
+## Webhooks (if applicable)
+
+### Events
+
+| Event              | Trigger              |
+| ------------------ | -------------------- |
+| `resource.created` | New resource created |
+| `resource.updated` | Resource updated     |
+| `resource.deleted` | Resource deleted     |
+
+### Payload
+
+```json
+{
+	"event": "resource.created",
+	"timestamp": "2025-01-01T00:00:00Z",
+	"data": {
+		"id": "abc-123",
+		"name": "Resource 1"
+	}
+}
+```
+
+---
+
+## SDKs & Examples
+
+### cURL
+
+```bash
+# List resources
+curl -X GET "https://api.example.com/v1/resources" \
+  -H "Authorization: Bearer TOKEN"
+
+# Create resource
+curl -X POST "https://api.example.com/v1/resources" \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "New Resource"}'
+```
+
+### TypeScript/JavaScript
+
+```typescript
+const response = await fetch('https://api.example.com/v1/resources', {
+	headers: { Authorization: `Bearer ${token}` }
+});
+const { data } = await response.json();
+```
+
+---
+
+## Changelog
+
+| Version | Date         | Changes             |
+| ------- | ------------ | ------------------- |
+| 1.0.0   | [YYYY-MM-DD] | Initial API release |