Skip to content

VSM Service Implementation Summary

Overview

Successfully implemented VSM (Value Stream Mapping) tracking service for issue #51.

Components Implemented

1. Service API (services/vsm/)

  • FastAPI Application (app/main.py):

  • POST /api/v1/work-items - Create work items

  • PUT /api/v1/work-items/{id}/transition - Move between stages
  • GET /api/v1/work-items/{id}/history - Get stage history
  • GET /api/v1/metrics - Flow metrics (throughput, WIP, cycle time)
  • GET /api/v1/stages - List available stages
  • GET /api/v1/health - Health check

  • GET /metrics - Prometheus metrics

  • Database Models (app/models.py):

  • WorkItem - Work items (features, bugs, tasks, epics)

  • Stage - Value stream stages (Backlog → Production)
  • StageTransition - Transition history

  • FlowMetrics - Aggregated metrics

  • Pydantic Schemas (app/schemas.py):

  • Request/response models with validation

  • OpenAPI documentation auto-generated

  • Prometheus Metrics:

  • vsm_requests_total - Request counter
  • vsm_work_items_created_total - Work items created
  • vsm_stage_transitions_total - Stage transitions
  • vsm_cycle_time_hours - Cycle time histogram
  • vsm_work_in_progress - WIP gauge by stage

2. Database Schema (services/vsm/migrations/)

  • Alembic Migrations:

  • Initial migration (001) creates all tables

  • Default stages pre-populated

  • Tables:

  • work_items - Work item tracking
  • stages - 6 default stages (Backlog → Production)
  • stage_transitions - Full transition history
  • flow_metrics - Aggregated flow metrics

3. Kubernetes Deployment (platform/apps/vsm-service/)

  • PostgreSQL Cluster (postgresql/db-vsm-cluster.yaml):

  • CloudNativePG cluster with HA (3 replicas)

  • Resource optimized (200m CPU, 256Mi memory)

  • Monitoring enabled

  • Service Manifests:

  • deployment.yaml - 2 replicas, health probes

  • service.yaml - ClusterIP service
  • ingress.yaml - External access
  • configmap.yaml - Configuration

  • serviceaccount.yaml - RBAC

  • ArgoCD Application (vsm-service-application.yaml):

  • Automated sync enabled
  • Sync wave 25 (after dependencies)

Acceptance Criteria Status

  • ✅ VSM service API deployed
  • ✅ Work item tracking across stages
  • ✅ Cycle time calculation per stage
  • ✅ Flow metrics collection (throughput, WIP, cycle time percentiles)
  • ✅ API documented (OpenAPI/Swagger)
  • ⏳ Passes AT-E2-005 (partial) - Ready for testing

Testing

Unit Tests

Location: services/vsm/tests/unit/

  • API endpoint validation
  • Request/response model validation
  • Health check verification

Run: cd services/vsm && pytest tests/unit -v

Validation Script

Location: services/vsm/validate.sh Tests all API endpoints end-to-end:

  1. Health check
  2. Create work item
  3. Stage transition
  4. Work item history
  5. Flow metrics
  6. List stages

Run: ./services/vsm/validate.sh

Deployment Instructions

Prerequisites

  • Kubernetes cluster with ArgoCD
  • CloudNativePG operator installed
  • Ingress controller configured

Deploy Steps

  1. Deploy PostgreSQL cluster:
kubectl apply -f platform/apps/postgresql/db-vsm-credentials.yaml
kubectl apply -f platform/apps/postgresql/db-vsm-cluster.yaml
  1. Wait for database to be ready:
kubectl wait --for=condition=Ready cluster/db-vsm-dev -n fawkes --timeout=300s
  1. Build and push Docker image:
cd services/vsm
./build.sh
docker tag vsm-service:latest <registry>/vsm-service:latest
docker push <registry>/vsm-service:latest
  1. Deploy via ArgoCD:
kubectl apply -f platform/apps/vsm-service-application.yaml
  1. Verify deployment:
kubectl get pods -n fawkes -l app=vsm-service
kubectl logs -n fawkes -l app=vsm-service
  1. Run validation:
export VSM_URL=http://vsm-service.127.0.0.1.nip.io
./services/vsm/validate.sh

API Usage Examples

Create Work Item

curl -X POST http://vsm-service.127.0.0.1.nip.io/api/v1/work-items \
  -H "Content-Type: application/json" \
  -d '{"title": "Implement feature X", "type": "feature"}'

Transition Stage

curl -X PUT http://vsm-service.127.0.0.1.nip.io/api/v1/work-items/1/transition \
  -H "Content-Type: application/json" \
  -d '{"to_stage": "Development"}'

Get Flow Metrics

curl http://vsm-service.127.0.0.1.nip.io/api/v1/metrics?days=7

View API Documentation

Open: http://vsm-service.127.0.0.1.nip.io/docs

Architecture

┌─────────────────┐
│   Work Items    │
│  (Features,     │
│   Bugs, etc)    │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│         Value Stream Stages             │
├─────────────────────────────────────────┤
│ Backlog → Analysis → Development →      │
│ Testing → Deployment → Production       │
└────────┬────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│  Flow Metrics   │
│ - Throughput    │
│ - WIP           │
│ - Cycle Time    │
└─────────────────┘

Security Features

  • Non-root container (UID/GID 10001)
  • Read-only root filesystem support
  • Security context constraints
  • No privileged escalation
  • Database credentials in secrets
  • TLS-ready PostgreSQL connections

Monitoring & Observability

  • Prometheus metrics endpoint (/metrics)
  • Health/readiness probes
  • Structured logging
  • OpenTelemetry instrumentation ready
  • Flow metrics tracking:
  • Throughput (items/period)
  • WIP (work in progress)
  • Cycle time (avg, p50, p85, p95)

Future Enhancements

  • [ ] Custom stage definitions
  • [ ] Work item dependencies
  • [ ] Team/project segmentation
  • [ ] SLA tracking
  • [ ] Automated flow metric aggregation
  • [ ] Grafana dashboard templates
  • [ ] Webhook notifications
  • [ ] REST API rate limiting
  • [ ] External Secrets Operator integration

Resources

  • Service Code: services/vsm/
  • K8s Manifests: platform/apps/vsm-service/
  • Database Schema: services/vsm/migrations/
  • Documentation: services/vsm/README.md
  • Issue: paruff/fawkes#51