Initial commit: ClaudeForge v1.0.0

2026-07-04 19:03:15 -04:00 · 2025-11-12 11:19:48 +01:00
commit 37422c1667
42 changed files with 11812 additions and 0 deletions
@@ -0,0 +1,345 @@
+# Backend Development Guidelines
+
+This file provides guidance for backend development in this project.
+
+## Overview
+
+Express API backend with TypeScript, PostgreSQL database, and Redis caching. RESTful API design with comprehensive error handling, testing, and security practices.
+
+## Project Structure
+
+```
+backend/
+├── src/
+│   ├── controllers/         # Route handlers
+│   │   ├── auth.controller.ts
+│   │   ├── user.controller.ts
+│   │   └── product.controller.ts
+│   ├── services/            # Business logic
+│   │   ├── auth.service.ts
+│   │   ├── user.service.ts
+│   │   └── product.service.ts
+│   ├── models/              # Database models
+│   │   ├── User.ts
+│   │   └── Product.ts
+│   ├── middleware/          # Express middleware
+│   │   ├── auth.middleware.ts
+│   │   ├── validation.middleware.ts
+│   │   └── error.middleware.ts
+│   ├── routes/              # Route definitions
+│   │   ├── auth.routes.ts
+│   │   ├── user.routes.ts
+│   │   └── product.routes.ts
+│   ├── utils/               # Utilities
+│   │   ├── logger.ts
+│   │   ├── validators.ts
+│   │   └── crypto.ts
+│   ├── config/              # Configuration
+│   │   ├── database.ts
+│   │   └── redis.ts
+│   └── index.ts             # App entry point
+├── tests/
+│   ├── unit/                # Unit tests
+│   ├── integration/         # Integration tests
+│   └── fixtures/            # Test data
+├── prisma/
+│   ├── schema.prisma        # Database schema
+│   └── migrations/          # Migration files
+├── .env.example
+├── package.json
+└── tsconfig.json
+```
+
+## File Structure
+
+- **controllers/** - Handle HTTP requests, validate input, call services
+- **services/** - Business logic layer, independent of HTTP
+- **models/** - Database models and Prisma client usage
+- **middleware/** - Express middleware (auth, validation, logging, errors)
+- **routes/** - Route definitions mapping URLs to controllers
+- **utils/** - Shared utility functions (logging, validation, crypto)
+- **config/** - Configuration files for database, Redis, etc.
+- **tests/** - Unit and integration tests
+
+## Architecture
+
+**Layer Pattern**: Controllers → Services → Models → Database
+
+**Flow**:
+```
+HTTP Request → Route → Middleware → Controller → Service → Model → Database
+                ↓
+            Response
+```
+
+**Components**:
+- **Controllers**: HTTP layer, request/response handling
+- **Services**: Business logic, reusable across controllers
+- **Models**: Data access layer with Prisma ORM
+- **Middleware**: Cross-cutting concerns (auth, logging, validation)
+
+## Setup & Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with:
+# - DATABASE_URL (PostgreSQL connection string)
+# - REDIS_URL (Redis connection string)
+# - JWT_SECRET (secret for token signing)
+# - PORT (default 3000)
+
+# Start PostgreSQL and Redis (using Docker)
+docker-compose up -d postgres redis
+
+# Run database migrations
+npx prisma migrate dev
+
+# Generate Prisma client
+npx prisma generate
+
+# Seed database
+npm run seed
+
+# Start development server
+npm run dev
+```
+
+## API Design
+
+### RESTful Conventions
+
+- Use RESTful conventions for API endpoints
+- Implement proper HTTP status codes:
+  - `200 OK` - Successful GET/PUT/PATCH
+  - `201 Created` - Successful POST
+  - `204 No Content` - Successful DELETE
+  - `400 Bad Request` - Validation error
+  - `401 Unauthorized` - Authentication required
+  - `403 Forbidden` - Insufficient permissions
+  - `404 Not Found` - Resource not found
+  - `500 Internal Server Error` - Server error
+
+### Versioning
+
+- Version APIs when breaking changes are needed
+- Format: `/api/v1/`, `/api/v2/`
+- Example: `/api/v1/users`, `/api/v2/users`
+
+### Documentation
+
+- Document all endpoints with OpenAPI/Swagger
+- Access docs at `/api-docs` when server running
+- Include request/response examples
+- Document authentication requirements
+
+### Naming Conventions
+
+- Use camelCase for JSON keys
+- Use snake_case for database columns
+- Use kebab-case for URL paths
+
+## Database Operations
+
+### Migrations
+
+- Use migrations for all schema changes
+- **Never edit existing migrations** - create new ones
+- Test migrations on copy of production data
+- Include both up and down migrations
+- Name migrations descriptively: `20250112_add_user_email_index`
+
+### Query Optimization
+
+- Implement proper indexes for frequently queried columns
+- Avoid N+1 queries - use joins or batch loading with Prisma `include`
+- Use `EXPLAIN ANALYZE` to analyze slow queries
+- Paginate large result sets (max 100 items per page)
+
+### Transactions
+
+- Use transactions for multi-step operations
+- Example:
+  ```typescript
+  await prisma.$transaction(async (tx) => {
+    await tx.user.update({ ... });
+    await tx.account.create({ ... });
+  });
+  ```
+
+## Error Handling
+
+### Global Error Middleware
+
+- Implement global error handling middleware
+- Catch all errors in one place
+- Log errors with context (request ID, user ID, timestamp)
+
+### Error Response Format
+
+Return consistent error response format:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "User-friendly message",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  }
+}
+```
+
+### Error Classes
+
+- Use custom error classes for different error types
+- Examples: `ValidationError`, `AuthenticationError`, `NotFoundError`
+- Never expose stack traces to clients in production
+- Log full stack traces server-side
+
+## Testing Requirements
+
+### Unit Tests
+
+- Write unit tests for business logic (services, utils)
+- Mock external dependencies (database, APIs, Redis)
+- Test edge cases and error conditions
+- Aim for 80%+ code coverage
+
+### Integration Tests
+
+- Write integration tests for API endpoints
+- Test full request/response cycle
+- Use test database (separate from dev/prod)
+- Reset database state between tests
+
+### Best Practices
+
+- Use test databases, never production
+- Use factories/fixtures for test data
+- Test authentication and authorization
+- Test error scenarios
+
+```bash
+# Run tests
+npm test                  # All tests
+npm run test:unit         # Unit tests only
+npm run test:integration  # Integration tests only
+npm run test:coverage     # With coverage report
+```
+
+## Security Practices
+
+### Input Validation
+
+- Validate all input data with validation middleware
+- Use schema validation (Joi, Zod, class-validator)
+- Sanitize user input to prevent XSS
+
+### Database Security
+
+- Use parameterized queries (Prisma handles this)
+- Prevents SQL injection
+- Never concatenate user input into queries
+
+### Authentication & Authorization
+
+- Hash passwords with bcrypt (minimum 10 rounds)
+- Use JWT for stateless authentication
+- Implement refresh token rotation
+- Use environment variables for secrets
+
+### Rate Limiting
+
+- Implement rate limiting on public endpoints
+- Example: 100 requests per 15 minutes per IP
+- Protect against brute force attacks
+
+### CORS
+
+- Implement proper CORS policies
+- Whitelist allowed origins
+- Don't use wildcard (`*`) in production
+
+## Performance Optimization
+
+### Caching
+
+- Implement caching for frequently accessed data
+- Use Redis for session storage and data caching
+- Cache expensive computations
+- Set appropriate TTL (time-to-live)
+
+### Database
+
+- Use database connection pooling (Prisma handles this)
+- Optimize queries with proper indexes
+- Monitor slow queries
+- Use read replicas for heavy read workloads
+
+### Async Operations
+
+- Use async/await for I/O operations
+- Never block the event loop
+- Use worker threads for CPU-intensive tasks
+- Queue background jobs with RabbitMQ/Bull
+
+## Logging
+
+- Use structured logging (Winston, Pino)
+- Log levels: ERROR, WARN, INFO, DEBUG
+- Include context: request ID, user ID, timestamp
+- Never log sensitive data (passwords, tokens)
+- Rotate log files in production
+
+## Common Commands
+
+```bash
+# Development
+npm run dev              # Start dev server with hot reload
+npm test                 # Run all tests
+npm run test:watch       # Run tests in watch mode
+npm run lint             # Run ESLint
+npm run format           # Format code with Prettier
+
+# Database
+npm run migrate          # Run migrations
+npm run migrate:rollback # Rollback last migration
+npm run migrate:reset    # Reset database (dev only)
+npm run seed             # Seed database with test data
+npx prisma studio        # Open Prisma Studio (DB GUI)
+
+# Production
+npm run build            # Build TypeScript
+npm start                # Start production server
+
+# Debugging
+npm run dev:debug        # Start with debugger
+npm run logs             # View application logs
+```
+
+## API Documentation
+
+After starting the server, access API documentation at:
+
+```
+http://localhost:3000/api-docs
+```
+
+Swagger UI provides interactive API documentation with:
+- All endpoints listed
+- Request/response schemas
+- Try-it-out functionality
+- Authentication examples
+
+---
+
+**Context**: Backend (Node.js/Express/TypeScript/PostgreSQL)
+**Lines**: ~200 (Backend-specific template with native format)