Skip to main content

ADR 0004: Status Surfacing

Status​

Accepted

Context​

Project status must be visible in Frappe CRM and the client portal. Stakeholders need real-time visibility into:

  • Build and test results
  • Deployment status across environments
  • Promotion events
  • Rollback events
  • Infrastructure health

Additionally:

  • CI/CD should emit standardized status events
  • Integration should be decoupled from CI/CD workflows
  • Multiple consumers may need access to status data (CRM, portal, mobile app)
  • Status data should be queryable and historical

Decision​

Define a Status Service API (OpenAPI-based) and post events from CI/CD workflows. A lightweight integration service maps events into Frappe CRM.

Architecture​

CI/CD Workflows → Status Service API → Integration Service → Frappe CRM
                                    ↓
                              Client Portal / Mobile App

Event Types​

  • build.started, build.completed, build.failed
  • test.started, test.completed, test.failed
  • deploy.started, deploy.completed, deploy.failed
  • promotion.requested, promotion.approved, promotion.completed
  • rollback.started, rollback.completed
  • health.degraded, health.restored

Event Schema​

{
  "event_type": "deploy.completed",
  "project_id": "proj-123",
  "environment": "production",
  "timestamp": "2026-03-25T10:30:00Z",
  "metadata": {
    "commit_sha": "abc123",
    "version": "v1.2.3",
    "deployed_by": "user@example.com"
  }
}

Consequences​

Positive​

  • CI/CD emits consistent events for build, test, deploy, promotion, and rollback
  • Frappe integration can be updated without changing CI workflows
  • Portal/mobile can poll or subscribe to the Status Service
  • Historical status data is queryable
  • Multiple consumers can access the same status data
  • Decoupled architecture allows for easier testing and maintenance

Negative​

  • Additional service to maintain (Status Service API)
  • Requires integration service for Frappe mapping
  • Network dependency for status updates
  • Potential delay in status visibility if service is down

Neutral​

  • Status Service needs monitoring and alerting
  • Retry logic should be implemented in CI workflows
  • API authentication should be configured (API tokens)
  • Rate limiting should be considered for high-frequency events

Implementation​

CI Workflow Integration​

- name: Report Build Status
  if: always()
  env:
    STATUS_API_URL: ${{ secrets.STATUS_API_URL }}
    STATUS_API_TOKEN: ${{ secrets.STATUS_API_TOKEN }}
  run: |
    curl -X POST "$STATUS_API_URL/events" \
      -H "Authorization: Bearer $STATUS_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "event_type": "build.completed",
        "project_id": "${{ vars.PROJECT_ID }}",
        "environment": "ci",
        "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
        "metadata": {
          "commit_sha": "${{ github.sha }}",
          "result": "${{ job.status }}"
        }
      }'

Status Service Requirements​

  • OpenAPI specification
  • Authentication via API tokens
  • Event persistence (database)
  • Query API for historical events
  • Webhook support for real-time notifications (optional)
  • Health check endpoint

Frappe Integration Service​

  • Poll Status Service API or receive webhooks
  • Map events to Frappe doctype operations
  • Handle Frappe authentication
  • Error handling and retry logic
  • Logging and monitoring