Regime Management System

A decision support and controlled automation system for grid trading strategies.

Project Structure

.
├── .kiro/specs/regime-management/    # Specification documents
│   ├── requirements.md               # System requirements
│   ├── design.md                    # System design document
│   └── tasks.md                     # Implementation task list
├── infra/                           # Kubernetes infrastructure
│   ├── metrics-service/             # Metrics service K8s manifests
│   │   ├── deployment.yaml          # Metrics service deployment
│   │   ├── service.yaml             # Metrics service service
│   │   ├── configmap.yaml           # Configuration
│   │   ├── external-secret.yaml     # ESO secret sync
│   │   └── n8n-workflow.yaml        # n8n workflow definition
│   ├── kustomization.yaml           # Kustomize configuration
│   ├── namespace.yaml               # Namespace definition
│   ├── Taskfile.yml                 # Infrastructure tasks
│   └── test-integration.py          # Integration tests
├── metrics-service/                 # Metrics collection service (Python/FastAPI)
│   ├── src/                         # Source code
│   │   ├── metrics/                 # Metrics collection system
│   │   │   ├── collector.py         # Webhook endpoint and data aggregation
│   │   │   └── history.py           # YAML storage with Git integration
│   │   └── __init__.py
│   ├── tests/                       # Unit tests
│   │   ├── test_collector.py
│   │   └── test_history.py
│   ├── Dockerfile                   # Container image definition
│   ├── main.py                      # FastAPI application
│   ├── run.py                       # Startup script
│   └── requirements.txt             # Python dependencies
└── README.md                        # This file

Infrastructure Setup

Prerequisites

• Kubernetes cluster with:
  • External Secrets Operator (ESO) configured
  • n8n operator installed
  • Central secret store configured
• Docker for building images
• Taskfile for task automation

Quick Start

1. Build and deploy the infrastructure:

   task infra:dev:setup

2. Check status:

   task infra:status

3. Run tests:

   task infra:test:all

4. Access the API:

   task infra:port-forward
   # Then visit http://localhost:8000/docs

Development Workflow

Following the ArgoCD development workflow for rapid iteration:

1. Build the Docker image:

   task infra:build

2. Apply directly to cluster (bypassing ArgoCD):

   task infra:apply

3. Test the deployment:

   task infra:test:e2e

4. View logs:

   task infra:logs

5. When ready, commit and let ArgoCD sync:

   git add . && git commit -m "Update metrics service"

Infrastructure Components

Metrics Service

• FastAPI application running in Kubernetes
• Health checks and monitoring
• Secret management via ESO (External Secrets Operator)
• Configuration via ConfigMaps
• No persistent storage - uses Git as persistence layer

n8n Scheduling

• Automated workflow that calls metrics collection every 5 minutes
• Error handling and logging
• Configurable schedule via n8n workflow

Security

• Credentials managed centrally via ESO
• No manual secret creation
• Automated secret distribution

Available Tasks

For a complete list of available tasks and development workflow guidance, see taskfile.md.

Key tasks to get started:

• task infra:dev:setup - Set up development environment
• task infra:status - Check infrastructure status
• task infra:test:all - Run all tests
• task metrics:dev - Start metrics service development server
• task docs - Update task documentation

Run task --list to see all available tasks.

Features Implemented

Task 1: Metrics Collection Infrastructure ✅

• MetricsCollector Service: Webhook endpoint for n8n triggers with system snapshot aggregation
• MetricsHistory Service: YAML storage with Git integration and timestamp-based naming
• System Snapshot Data: Collects account balance, grid status, market data, and regime state
• Error Handling: Graceful failure handling without affecting trading operations
• n8n Integration: Structured responses for workflow tracking
• Kubernetes Deployment: Full infrastructure-as-code setup
• Automated Scheduling: n8n workflow for regular metrics collection

API Endpoints

• GET /health - Health check endpoint
• POST /metrics/collect - Metrics collection webhook for n8n
• GET /docs - Interactive API documentation (Swagger UI)
• GET /redoc - Alternative API documentation

Requirements Satisfied

• 15.1: Webhook endpoint for n8n triggered metrics collection ✅
• 15.6: YAML storage with Git integration for metrics history ✅
• 15.8: n8n workflow automation for scheduled collection ✅
• Infrastructure: Complete Kubernetes deployment with ESO secret management ✅