Global Conventions¶

The system follows consistent conventions across all components to ensure maintainability and developer productivity.

Naming Standards¶

Services follow consistent naming patterns across all layers:

For comprehensive naming and code style guidelines, see Code Standards.

Logging & Monitoring Practices¶

All components implement structured logging with consistent format:

Log Format¶

JSON structured logs for machine parsing:

{
  "timestamp": "2025-11-11T10:30:00Z",
  "level": "INFO",
  "service": "backend-api",
  "correlation_id": "abc-123-def",
  "user_id": "user@epfl.ch",
  "message": "Emissions calculated",
  "duration_ms": 45,
  "metadata": {
    "distance": 100,
    "mode": "car"
  }
}

Log Levels¶

Use consistent log levels across all services:

• DEBUG: Detailed diagnostic information for development
• INFO: General informational messages about system operation
• WARNING: Unexpected situations that don't prevent operation
• ERROR: Errors that prevent specific operations from completing
• CRITICAL: System-level failures requiring immediate attention

Correlation IDs¶

Every request gets a unique correlation ID for tracing:

• Generated at API gateway
• Propagated through all services
• Included in all log entries
• Returned in API responses

Performance Metrics¶

All services expose Prometheus metrics:

• Request count and duration
• Error rates
• Queue depths
• Database connection pool status
• Cache hit rates

Access metrics at /metrics endpoint on each service.

Secret Management Policy¶

Secrets are never stored in code or version control:

Local Development¶

• Create .env files from .env.example templates
• Store locally, never commit
• One .env per service

Cloud Environments¶

• Infisical for central secret management
• Infisical CRD creates Kubernetes secrets automatically
• Azure Key Vault for production-critical secrets
• Environment variables injected at runtime

Secret Categories¶

Error Handling Patterns¶

All APIs follow standardized error response format:

Error Response Structure¶

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Distance must be a positive number",
    "details": {
      "field": "distance",
      "value": -10,
      "constraint": "positive"
    },
    "correlation_id": "abc-123-def",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}

HTTP Status Codes¶

Use proper HTTP status codes consistently:

Error Codes¶

Use consistent error code prefixes:

• AUTH_* - Authentication/authorization errors
• VALID_* - Validation errors
• DB_* - Database errors
• EXT_* - External service errors
• SYS_* - System/infrastructure errors

API Response Standards¶

All REST API responses follow consistent structure:

Success Response¶

{
  "data": {
    "id": 123,
    "emissions": 20.5,
    "unit": "kg_co2"
  },
  "metadata": {
    "timestamp": "2025-11-11T10:30:00Z",
    "version": "v1"
  }
}

List Response with Pagination¶

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  },
  "links": {
    "self": "/api/v1/emissions?page=1",
    "next": "/api/v1/emissions?page=2",
    "prev": null
  }
}

API Versioning¶

API versions in URL path: /api/v1/resource

Breaking changes require new version: /api/v2/resource

Maintain backward compatibility for minimum 6 months.

Code Quality Standards¶

All code must meet minimum quality gates before merge:

Backend (Python / FastAPI)¶

• Follow PEP 8, PEP 484 typing standards
• Type hints required for all public functions
• Ruff formatter and Ruff linter must pass
• Async/await preferred for I/O operations
• 60% minimum test coverage with pytest
• FastAPI generates valid OpenAPI documentation

Frontend (Vue / Quasar)¶

• Vue 3 Composition API with <script setup> syntax
• TypeScript encouraged for new code
• Pinia for global state management
• ESLint and Prettier must pass
• All UI text via i18n ($t() function)
• WCAG AA accessibility compliance
• 60% minimum test coverage with Vitest

For complete coding standards, see Code Standards.

Version Control Workflow¶

Project uses three-tier promotion model:

Branch naming:

• feature/<issue> - New features
• fix/<issue> - Bug fixes
• chore/<description> - Non-functional changes

Commit format:

Use Conventional Commits: feat:, fix:, chore:, docs:

Review requirements:

• 2 reviewers minimum for security-critical code
• CI checks must pass before merge
• Product owner approval required for stage/main

For detailed workflow, see Workflow Guide.

Observability Requirements¶

All services must implement standard observability practices:

Metrics Endpoint¶

Expose /metrics endpoint with Prometheus format:

• Request count and duration
• Error rates by type
• Resource utilization (CPU, memory)
• Business metrics (calculations performed)

Distributed Tracing¶

Use OpenTelemetry for request tracing:

• Trace context propagated across services
• Span created for each major operation
• Critical paths instrumented

Structured Logging¶

Include correlation IDs in all log entries for request tracing.

For monitoring setup, see Infrastructure Monitoring.

Performance Targets¶

System must meet these baseline performance requirements:

Best practices:

• Stateless design for horizontal scaling
• Redis caching for emission factors
• Database connection pooling
• CDN for static assets
• Lazy loading for frontend routes

For scaling strategy, see Scalability.

Documentation Standards¶

Keep documentation concise and actionable:

• Target 500-800 words per document (10-minute read) Okay if < 1200 words
• Use active voice and imperative mood
• Wrap text at 72 characters
• Include examples after concepts
• Add cross-references to related docs
• Avoid duplicating content across files

Update documentation in the same PR as code changes.

For detailed conventions and code examples, see the Code Standards documentation and individual component guides.