Development Project Guidelines Example

---
title: E-Commerce API Project Guidelines
version: 1.0.0
created: 2025-04-10
purpose: Provide guidance for working with the e-commerce API project
---

# E-Commerce API Project Guidelines

## Project Purpose and Scope

This project is a RESTful API for an e-commerce platform built using Node.js and Express. It provides endpoints for product management, user authentication, order processing, and payment integration. The API serves both the customer-facing web/mobile applications and the internal admin dashboard.

Key objectives:
- Provide a secure, performant API for e-commerce operations
- Support high-volume traffic (up to 1,000 requests/second)
- Maintain 99.9% uptime and <100ms average response time
- Process transactions with PCI-DSS compliant payment gateways
- Allow for future integration with third-party services

Scope limitations:
- Does not handle frontend UI (separate projects handle this)
- Does not manage shipping logistics (integrates with external shipping APIs)
- Not responsible for data analytics (sends data to separate analytics service)

## Restrictions and Guardrails

### Security Requirements

1. Authentication:
   - All endpoints except /login, /register, and product browsing require JWT authentication
   - Tokens expire after 24 hours
   - Use refresh tokens for re-authentication
   - No sensitive data in JWTs

2. Data Protection:
   - All PII must be encrypted at rest using AES-256
   - Payment data must never be stored, only forwarded to payment processor
   - Logs must not contain sensitive information (no PII, no passwords, no payment details)

3. Access Patterns:
   - Read from: services/, models/, utils/, config/
   - Write to: controllers/, tests/, documentation/
   - Never modify: security/, middlewares/auth.js

4. Code Safety:
   - Input validation required for all endpoints using validation/schemas
   - Rate limiting applied to all endpoints (see config/rate-limits.js)
   - Prevent SQL injection using parameterized queries only

### Performance Requirements

1. Response Time:
   - API endpoints must respond in <100ms (p95)
   - Batch operations must complete in <500ms
   - Long-running tasks must be queued for async processing

2. Database:
   - Use indexes for all frequently queried fields
   - Implement query caching for product and category listings
   - Use connection pooling with max 20 connections

3. Resource Usage:
   - Memory usage <500MB per instance
   - CPU usage <70% sustained
   - Scale horizontally beyond these thresholds

## Available Resources

### Project Structure

- /src
  - /controllers - Route handlers
  - /models - Database models
  - /services - Business logic
  - /utils - Helper functions
  - /middleware - Express middleware
  - /config - Configuration files
  - /documentation - API documentation
  - /tests - Unit and integration tests

### External Services

1. Payment Gateway: Stripe
   - Endpoint: https://api.stripe.com/v1
   - Authentication: API key in .env (STRIPE_SECRET_KEY)
   - Documentation: See /documentation/stripe-integration.md
   - Rate limits: 100 requests/second

2. Product Database: MongoDB Atlas
   - Connection: MongoDB connection string in .env (MONGO_URI)
   - Collections: products, categories, inventory
   - Indexes: See /documentation/database-schema.md
   - Query Restrictions: Use aggregation framework for complex queries

3. User Auth Service: Auth0
   - Endpoint: https://your-tenant.auth0.com
   - Authentication: API keys in .env (AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET)
   - Rate limits: 50 requests/second

## Tool Usage Guidelines

### Testing Framework

1. Using Jest and Supertest:
   - All endpoints must have integration tests
   - All services must have unit tests
   - Run tests with coverage report before PR submission
   - E2E tests run on staging only

2. CI/CD:
   - GitHub Actions for CI (see .github/workflows)
   - Tests run on each PR and push to main
   - Deployment triggered on successful merge to main

### Code Style & Documentation

1. Code Style:
   - ESLint with Airbnb style guide
   - Prettier with project-specific settings in .prettierrc
   - TypeScript with strict mode enabled

2. API Documentation:
   - OpenAPI/Swagger for endpoint documentation
   - JSDoc for function documentation
   - README for setup and overview

## Error Handling

1. API Errors:
   - Use standard error response format (see /utils/error-handler.js)
   - Include error code, message, and request ID
   - Log detailed error information (except PII)

2. Service Failures:
   - Implement circuit breakers for external service calls
   - Retry with exponential backoff for transient failures
   - Fallback to degraded service when dependencies unavailable

3. Monitoring:
   - Use Sentry for error tracking
   - Set up alerts for error rate increases
   - Log all errors to CloudWatch

## Deployment & Operations

1. Environments:
   - Development: Local only, use .env.development
   - Staging: AWS ECS, use .env.staging
   - Production: AWS ECS, use .env.production

2. Release Process:
   - Feature branches → PR → main → auto-deploy to staging
   - Manual promotion from staging to production
   - Rollback procedure: See /documentation/rollback-procedure.md

3. Monitoring:
   - Datadog for performance monitoring
   - Prometheus for metrics
   - Grafana for dashboards
   - PagerDuty for on-call alerts