Skip to content
Mahoosuc OS Documentation

Devflow

Product: products/devflow/

DevFlow is a comprehensive development workflow automation platform that streamlines code development, testing, deployment, and monitoring.

DevFlow is a comprehensive development workflow automation platform that streamlines code development, testing, deployment, and monitoring.

Architecture

DevFlow follows a microservices architecture with 7 independent services:

1. devflow-api (Port 3100)

Public API gateway for DevFlow product

  • Authentication and authorization
  • Rate limiting
  • Request routing to microservices
  • RESTful API endpoints

Endpoints:

  • /api/v1/projects/* - Project management
  • /api/v1/deployments/* - Deployment operations
  • /api/v1/tests/* - Test execution

2. devflow-devb (Port 3101)

DEVB System - Design-Emulate-Validate-Build

  • Design specification generation
  • Design emulation (dry-run, static-analysis, simulation)
  • Multi-perspective validation (Security, Performance, Cost, UX)
  • Complete specification generation

Key Services:

  • spec-generator.ts - 1,980 lines of specification logic
  • validation-engine.ts - 1,382 lines of validation logic

3. devflow-cicd (Port 3102)

CI/CD Pipeline Execution

  • GitHub Actions integration
  • GitLab CI integration
  • Pipeline stage management
  • Deployment orchestration

External Integrations:

  • GitHub API
  • GitLab API
  • Docker registries

4. devflow-testing (Port 3103)

Test Execution & Coverage

  • Unit test execution
  • Integration test execution
  • E2E test execution
  • Coverage tracking and reporting

5. devflow-monitoring (Port 3104)

Application Monitoring

  • Prometheus metrics queries
  • Grafana dashboard integration
  • Loki log aggregation
  • Alert rule management

6. devflow-worker (Background)

Async Job Processing

  • Redis-backed job queue
  • Code analysis tasks
  • Test execution
  • Deployment tasks
  • 3 concurrent workers

7. devflow-frontend (Port 3105)

React SPA UI

  • Project dashboard
  • Deployment history
  • Test results visualization
  • Real-time monitoring

Database Schema

DevFlow uses the devflow_db database with ~52 tables organized into:

  • Projects (~15 tables) - projects, repositories, branches, commits
  • DEVB System (~20 tables) - designs, emulations, validations
  • CI/CD (~12 tables) - pipelines, stages, deployments, environments
  • Monitoring (~5 tables) - metric definitions, alert rules, incidents

Quick Start

Prerequisites

  1. Shared infrastructure running (PostgreSQL, Redis, etc.)
  2. Docker and Docker Compose installed
  3. Environment variables configured

Setup

Terminal window
# 1. Copy environment template
cp .env.devflow.template .env.devflow


# 2. Update environment variables
nano .env.devflow


# 3. Start all DevFlow services
docker-compose up -d


# 4. Verify health
./scripts/verify-devflow.sh

Access URLs

ServiceURLPurpose
APIhttp://localhost:3100REST API gateway
DEVBhttp://localhost:3101Design system
CI/CDhttp://localhost:3102Pipeline management
Testinghttp://localhost:3103Test execution
Monitoringhttp://localhost:3104Metrics & logs
Frontendhttp://localhost:3105Web UI

Commands

DevFlow includes 43 type-safe commands organized by category:

dev (Development)

  • implement - Implement a new feature with TDD
  • test - Run tests with coverage
  • review - Code review automation
  • refactor - Intelligent refactoring
  • debug - Debug production issues

devops (DevOps)

  • deploy - Deploy to environment
  • rollback - Emergency rollback
  • monitor - Monitor deployment
  • scale - Scale services
  • cost-analyze - Analyze cloud costs

design (Design System)

  • solution - Create design specification
  • emulate - Emulate design (dry-run)
  • validate - Validate design
  • spec - Generate complete specs

db (Database)

  • migrate - Run migrations
  • backup - Backup database
  • restore - Restore from backup
  • query - Execute queries

docker (Containers)

  • build - Build container images
  • push - Push to registry
  • scan - Security scan
  • optimize - Optimize image size

Development

Project Structure

products/devflow/
├── services/
│   ├── api/           # API gateway service
│   ├── devb/          # DEVB system service
│   ├── cicd/          # CI/CD service
│   ├── testing/       # Testing service
│   ├── monitoring/    # Monitoring service
│   ├── worker/        # Background worker
│   └── frontend/      # React frontend
├── commands/
│   ├── dev/           # Development commands
│   ├── devops/        # DevOps commands
│   ├── design/        # Design commands
│   ├── db/            # Database commands
│   └── docker/        # Docker commands
├── database/
│   └── migrations/    # SQL migration files
├── docker-compose.yml
└── README.md

Adding a New Command

products/devflow/commands/dev/new-command.ts
import { CommandBase, CommandContext, CommandResult } from '@mahoosuc/command-framework'
import { z } from 'zod'


const schema = z.object({
  // Define arguments
})


export class NewCommand extends CommandBase<typeof schema> {
  name = 'new-command'
  category = 'dev'
  description = 'Description of the command'
  schema = schema


  async execute(args, ctx) {
    // Implementation
    return { success: true, message: 'Done' }
  }
}

Adding a New Service

  1. Create service directory: services/new-service/
  2. Add Dockerfile and package.json
  3. Implement service logic in src/
  4. Add to docker-compose.yml
  5. Update documentation

Testing

Terminal window
# Run all tests
npm run test


# Run service-specific tests
npm run test:api
npm run test:devb
npm run test:cicd


# E2E tests
npm run test:e2e


# Coverage report
npm run test:coverage

Deployment

Staging

Terminal window
docker-compose -f docker-compose.staging.yml up -d

Production

Terminal window
# Build production images
docker-compose build --no-cache


# Push to registry
docker-compose push


# Deploy with rolling update
docker-compose -f docker-compose.prod.yml up -d --remove-orphans

Monitoring

Prometheus Metrics

All services expose metrics at /metrics:

  • devflow_api_requests_total - Total API requests
  • devflow_api_request_duration_seconds - Request latency
  • devflow_pipeline_executions_total - Pipeline executions
  • devflow_test_runs_total - Test runs
  • devflow_deployments_total - Deployments

Grafana Dashboards

Pre-configured dashboards:

  • DevFlow Overview
  • API Performance
  • Pipeline Success Rate
  • Test Coverage Trends
  • Deployment Frequency

Logs

All services log to stdout/stderr, collected by Promtail and sent to Loki:

Terminal window
# Query logs via Loki
curl -G http://localhost:3101/loki/api/v1/query \
  --data-urlencode 'query={product="devflow"}'

Troubleshooting

Services won’t start

Terminal window
# Check logs
docker-compose logs -f


# Restart specific service
docker-compose restart devflow-api


# Full restart
docker-compose down && docker-compose up -d

Database connection issues

Terminal window
# Test database connection
docker exec shared-postgres pg_isready -U postgres


# Check devflow_db exists
docker exec shared-postgres psql -U postgres -l | grep devflow

API returning 500 errors

Terminal window
# Check API logs
docker-compose logs devflow-api


# Check database migrations
npm run db:status


# Run pending migrations
npm run db:migrate

Migration from Monolith

DevFlow was extracted from a monolithic architecture using the Strangler Fig pattern:

  1. Week 1-2: Service extraction and directory setup
  2. Week 3-4: Database migration (52 tables) with dual-write
  3. Week 5-6: Containerization and local testing
  4. Week 7-8: Command migration (43 commands)
  5. Week 9-10: Production deployment with gradual cutover

Support

For issues or questions:

License

MIT © Mahoosuc Solutions