Skip to main content

ARC // OS — Performance & Load Testing

Performance and load testing documentation for ARC // OS API endpoints.

Overview​

Performance testing ensures the API responds quickly and efficiently under normal and high load conditions. Load testing simulates multiple concurrent users to verify system stability and scalability.

Performance Benchmarks​

Response Time Targets​

Simple GET Requests:

  • Target: < 500ms
  • Examples: /api/days/today, /api/tasks, /api/exercises

Complex GET Requests:

  • Target: < 1000ms
  • Examples: /api/weeks/:date (with all days), /api/meals/nutrition/history

POST/PATCH/DELETE Requests:

  • Target: < 500ms
  • Examples: Creating tasks, meals, body composition entries

Week Generation:

  • Target: < 2000ms
  • Example: /api/weeks/generate

Concurrent Request Targets​

Concurrent GET Requests:

  • 10 concurrent: < 2000ms total
  • 20 concurrent: < 3000ms total

Concurrent Write Operations:

  • 10 concurrent creates: < 2000ms total
  • Mixed read/write (10 operations): < 2500ms total

Large Dataset Performance​

Listing Endpoints:

  • 50 tasks: < 1000ms
  • 30 exercises: < 1000ms
  • Week with 7 days + data: < 1500ms

Filtered Queries:

  • Tasks with dayId filter: < 500ms
  • Exercises by type: < 500ms

Sustained Load​

Sequential Requests:

  • 50 requests over time: Average < 500ms, Max < 2000ms
  • No degradation: Second half shouldn't be > 2x slower than first half

Load Testing Scenarios​

Scenario 1: Concurrent User Read Operations​

Setup:

  • 20 concurrent GET requests to /api/days/today
  • All authenticated users

Expected:

  • All requests complete successfully (200 status)
  • Total time < 3000ms
  • No errors or timeouts

Scenario 2: Concurrent Write Operations​

Setup:

  • 10 concurrent POST requests to /api/tasks
  • All authenticated users

Expected:

  • All requests complete successfully (201 status)
  • Total time < 2000ms
  • All tasks created correctly

Scenario 3: Mixed Read/Write Load​

Setup:

  • 5 concurrent GET requests
  • 5 concurrent POST requests
  • Mixed operations

Expected:

  • All requests complete successfully
  • Total time < 2500ms
  • No data corruption or race conditions

Scenario 4: Sustained Load Over Time​

Setup:

  • 50 sequential requests with 10ms delay between each
  • Simulates real user usage pattern

Expected:

  • Average response time < 500ms
  • Maximum response time < 2000ms
  • Minimum response time < 300ms
  • No performance degradation over time

Running Performance Tests​

Backend Performance Tests​

cd server
pnpm test performance.test.ts

Running Specific Test Suites​

# Response time tests only
pnpm test performance.test.ts -t "Response Time"

# Load testing only
pnpm test performance.test.ts -t "Load Testing"

# Large dataset tests only
pnpm test performance.test.ts -t "Large Dataset"

Verbose Output​

pnpm test performance.test.ts --reporter=verbose

Performance Test Coverage​

Endpoints Tested​

Core Endpoints:

  • ✅ /api/days/today - Simple GET
  • ✅ /api/weeks/generate - Week generation
  • ✅ /api/weeks/:date - Week view with data
  • ✅ /api/tasks - Task listing and creation
  • ✅ /api/exercises - Exercise listing
  • ✅ /api/checklist/:dayId/toggle/:key - Checklist operations

Additional Endpoints:

  • ✅ /api/meals - Meal creation
  • ✅ /api/meals/nutrition/history - Nutrition history query
  • ✅ /api/body-composition - Body composition creation
  • ✅ /api/cardio - Cardio session creation

Test Categories​

  1. Response Time Performance

    • Simple GET requests
    • Multiple concurrent GET requests
    • Week generation

  2. Large Dataset Performance

    • Listing many tasks
    • Listing many exercises
    • Week with all days and data

  3. Concurrent Write Operations

    • Concurrent task creation
    • Concurrent checklist toggles

  4. Database Query Performance

    • Filtered task queries
    • Filtered exercise queries

  5. Memory and Resource Management

    • Sequential requests without degradation
    • Sustained load over time

  6. Load Testing - Concurrent Users

    • 20 concurrent GET requests
    • 10 concurrent task creations
    • Mixed read/write operations
    • Sustained load (50 requests)

  7. Additional Endpoint Performance

    • Meal creation
    • Body composition creation
    • Cardio session creation
    • Nutrition history queries

Performance Monitoring​

Metrics to Track​

  1. Response Times

    • Average response time
    • P50 (median)
    • P95 (95th percentile)
    • P99 (99th percentile)
    • Maximum response time

  2. Throughput

    • Requests per second
    • Successful requests per second
    • Failed requests per second

  3. Error Rates

    • HTTP error rates (4xx, 5xx)
    • Timeout rates
    • Database connection errors

  4. Resource Usage

    • CPU usage
    • Memory usage
    • Database connection pool usage
    • Database query times

Monitoring in Production​

Recommended Tools:

  • Application performance monitoring (APM)
  • Database query monitoring
  • Server resource monitoring
  • Log aggregation and analysis

Performance Optimization​

Database Optimization​

  1. Indexes

    • Ensure indexes on frequently queried fields
    • Review query plans for slow queries
    • Monitor index usage

  2. Query Optimization

    • Use select statements to limit returned fields
    • Implement pagination for large datasets
    • Avoid N+1 query problems

  3. Connection Pooling

    • Configure appropriate pool size
    • Monitor connection pool usage
    • Handle connection timeouts gracefully

API Optimization​

  1. Caching

    • Cache frequently accessed data
    • Implement cache invalidation strategies
    • Use appropriate cache TTLs

  2. Response Compression

    • Enable gzip compression
    • Compress large JSON responses

  3. Pagination

    • Implement pagination for list endpoints
    • Limit maximum page size
    • Provide total count when needed

Load Testing Best Practices​

  1. Start Small

    • Begin with low concurrency
    • Gradually increase load
    • Monitor for issues at each level

  2. Realistic Scenarios

    • Test with realistic data volumes
    • Simulate actual user behavior
    • Include delays between requests

  3. Monitor Resources

    • Watch CPU, memory, and database usage
    • Identify bottlenecks early
    • Test on production-like environment

  4. Clean Up

    • Clean up test data after tests
    • Reset database state
    • Close connections properly

  5. Document Results

    • Record performance metrics
    • Note any issues or bottlenecks
    • Track improvements over time

Troubleshooting Performance Issues​

Slow Response Times​

  1. Check Database Queries

    • Review slow query logs
    • Check for missing indexes
    • Optimize complex queries

  2. Check Resource Usage

    • Monitor CPU and memory
    • Check database connection pool
    • Review server logs

  3. Check Network

    • Verify network latency
    • Check for connection issues
    • Review DNS resolution

High Error Rates​

  1. Check Database Connections

    • Verify connection pool size
    • Check for connection leaks
    • Review connection timeout settings

  2. Check Application Logs

    • Review error logs
    • Check for exceptions
    • Verify error handling

  3. Check Resource Limits

    • Verify memory limits
    • Check CPU limits
    • Review process limits

Future Enhancements​

  1. Automated Performance Testing

    • Integrate into CI/CD pipeline
    • Run on every deployment
    • Alert on performance regressions

  2. Advanced Load Testing

    • Use dedicated load testing tools (k6, Artillery, etc.)
    • Test with higher concurrency
    • Simulate realistic user patterns

  3. Performance Profiling

    • Add performance profiling
    • Identify hot paths
    • Optimize critical paths

  4. Real User Monitoring

    • Track real user performance
    • Monitor production performance
    • Alert on performance degradation

Last Updated: 2026-01-23
Status: Performance and load testing implemented and documented