Version 1.8 | February 2026
Agentic portfolio brain for migration and modernization.
Refactorium is an agentic AI platform that scores your portfolio, chooses the right 7R path, and coordinates humans and agents to refactor, rewrite, and migrate applications safely.
Refactorium is a phased agentic platform that assesses application portfolios, makes data-driven 7R strategy recommendations, and orchestrates modernization/migration workflows with human oversight and continuous learning.
It ships with a full web application (FastAPI + Pico CSS + HTMX) providing a real-time portfolio dashboard, approval workflows, agent execution console, source code ingestion, and a program manager dashboard for executive tracking.
Key characteristics:
- Portfolio-level decision making (multiple apps, waves, dependencies)
- Human-in-the-loop approvals for high-risk decisions
- Learning loop: feedback from humans and outcomes informs future agent decisions
- Reusable across stacks (Java, .NET, mainframe, etc.) and cloud targets (Azure, AWS, GCP)
- Web-based UI with real-time SSE-powered agent execution
- LLM message transparency: see the actual prompts and responses during agent runs
| Agent | Responsibility |
|---|---|
| 7R Strategy Agent | Score app on tech/business/risk; recommend rehost/replatform/refactor/rewrite/retire/repurchase/relocate |
| Security Scanning Agent | Analyze apps for OWASP Top 10 vulnerabilities, dependency CVEs, misconfigurations |
| Compliance Agent | Assess against SOC 2, HIPAA, PCI-DSS, GDPR and other compliance frameworks |
| Remediation Agent | Generate actual code fixes for security vulnerabilities and compliance gaps |
| Discovery & Spec Agent | Extract architecture, components, APIs, data flows from legacy code/configs |
| Modernization (Code) Agent | Refactor or rewrite code in target stack; upgrade frameworks; apply patterns |
| Infra & Pipeline Agent | Generate IaC (Bicep/Terraform), CI/CD pipelines, deployment manifests |
| Testing & Validation Agent | Generate tests; compare legacy vs. modern behavior; report gaps |
| Data Migration Agent | Design data migration scripts; schema evolution; cutover plans |
| Docs & Knowledge Agent | Maintain ADRs, runbooks, decision logs, architecture documentation |
| Agent | Responsibility |
|---|---|
| Organization Discovery Agent | Scan GitHub orgs, Azure DevOps projects, ServiceNow CMDB, or local repos to auto-discover applications |
| Portfolio Inventory Agent | Build normalized app catalog from CMDB, discovery tools, Git, monitoring |
| Wave Planning Agent | Group apps into migration waves based on dependencies, risk, business priority |
| Team Scoping Agent | Determine team composition, required skills, training needs per wave |
| Level of Effort Agent | Estimate migration effort per app with confidence intervals |
| Program Manager Agent | Synthesize portfolio data into executive status reports |
| Learning / Feedback Agent | Analyze approval patterns; propose threshold and rule adjustments |
| Component | Technology | Purpose |
|---|---|---|
| Backend | FastAPI (Python) | REST/HTML endpoints, session auth, background tasks |
| Frontend | Pico CSS v2 + HTMX | Responsive semantic HTML, partial page updates |
| Real-time | Server-Sent Events (SSE) | Live agent execution logs and LLM message streaming |
| Templates | Jinja2 | Server-side rendering with HTMX partials |
| Auth | Session-based (bcrypt) | Username/email login, admin bootstrap |
| Route | Page | Description |
|---|---|---|
/ |
Portfolio | App inventory table with 7R scores, strategy badges, CSV upload |
/discovery |
Discovery | Auto-discover apps from GitHub, Azure DevOps, CMDB, or local repos |
/apps/{id} |
App Detail | Per-app 7R decision, modernization results, source code ingestion |
/waves |
Waves | Wave plan with team requirements and effort estimates |
/approvals |
Approvals | Pending/resolved approval queue with inline review |
/program |
Program Dashboard | KPIs, AI-generated PM report, risks & blockers, wave progress tracking |
/learning |
Learning | Feedback insights from approval patterns |
/knowledge |
Knowledge Base | RAG document management, collection ingestion, file upload, URL fetching |
/agents |
Agent Console | Real-time pipeline execution with SSE log streaming and LLM message viewer |
/admin |
Admin | System health, model configuration, data files, audit log with LLM message history |
/admin/traces |
Traces | Distributed tracing viewer for HTTP requests, LLM calls, and RAG operations |
- Python 3.12+
- An Anthropic API key
- Clone the repository
- Create and activate a virtual environment
- Install dependencies:
pip install -r requirements.txt - Set your API key:
export ANTHROPIC_API_KEY="sk-ant-..." - Start the server:
uvicorn web.app:app --reload --port 8000 - Open
http://localhost:8000and create an admin account
See docs/user-guide.md for detailed usage instructions.
Refactorium supports flexible backend configuration for local development and Azure deployment. Each service can be configured independently:
| Service | Local (default) | Azure/Production |
|---|---|---|
| Storage | JSON/CSV files (file) |
PostgreSQL (postgres) |
| Cache | In-memory (memory) |
Redis (redis) |
| Tasks | Daemon threads (thread) |
Celery + Redis (celery) |
| AI | Anthropic API (anthropic) |
Azure AI Foundry (azure) or OpenAI (openai) |
| RAG | ChromaDB (chroma) |
Azure AI Search (azure) |
| Tracing | In-memory viewer (memory) |
Azure Monitor (azure) |
| Secrets | Environment variables | Azure Key Vault |
# Backend Selection
STORAGE_BACKEND=file # file (default) or postgres
CACHE_BACKEND=memory # memory (default) or redis
TASK_BACKEND=thread # thread (default) or celery
AI_BACKEND=anthropic # anthropic (default), azure, or openai
RAG_BACKEND=chroma # chroma (default), azure, or none
# AI Configuration
ANTHROPIC_API_KEY=sk-ant-... # Required for AI_BACKEND=anthropic
REFACTORIUM_MODEL=claude-sonnet-4-20250514
# OpenAI (when AI_BACKEND=openai)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
# Azure AI Foundry (when AI_BACKEND=azure)
AZURE_AI_ENDPOINT=https://your-ai.cognitiveservices.azure.com/
AZURE_AI_MODEL_DEPLOYMENT=claude-sonnet
# Celery (when TASK_BACKEND=celery)
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0
# Azure Key Vault (optional - loads secrets from vault instead of env)
AZURE_KEY_VAULT_URL=https://your-keyvault.vault.azure.net/
# Observability / Tracing (optional)
OTEL_ENABLED=true # Enable distributed tracing
OTEL_EXPORTER=memory,azure # memory (built-in viewer), azure, otlp, console
APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=... # For Azure MonitorSee .env.example for full configuration options.
The Admin dashboard displays current backend status at /admin.
- Discover Applications — Auto-discover apps from GitHub orgs, Azure DevOps, CMDB, or local repos (or upload CSV)
- Run Assessment — Execute the full portfolio pipeline to assess all apps
- Review Decisions — View 7R strategy recommendations on each app's detail page
- Approve/Reject — Review high-risk decisions requiring human approval
- Ingest Source Code — Upload ZIP or clone Git repos for deeper analysis
- Run Modernization — Execute single-app modernization pipelines
- Track Progress — Update app statuses and generate PM reports
- Analyze Feedback — Review learning insights to improve agent accuracy
Each application is scored across 10 dimensions (1-5 scale):
Technical:
- T1: Platform Support Risk
- T2: Architecture Brittleness
- T3: Operational Issues
- T4: Integration Complexity
Business:
- B1: Business Criticality
- B2: Change Velocity
- B3: UX Gaps
- B4: Time Pressure
Risk:
- R1: Security/Compliance Gaps
- R2: Data Residency
The combined scores drive the strategy recommendation: Rehost, Replatform, Refactor, Rewrite, Retire, Repurchase, Retain, or Relocate.
| Phase | Focus | Deliverables |
|---|---|---|
| Phase 1 | 7R Engine + Approvals | Portfolio catalog, 7R decisions, approval requests, wave plan, team requirements, effort estimates |
| Phase 2 | Single-App Deep Flow | Architecture spec, modernization plan, refactored code, IaC, CI/CD, tests, migration scripts, ADRs |
| Phase 3 | Multi-App Portfolio | Multiple apps with 7R decisions, intelligent wave assignments, staffing plan, portfolio-level LOE |
| Phase 4 | Human-in-the-Loop + Learning | Approval audit trail, learning insights, threshold/rule/prompt updates |
| File | Content |
|---|---|
data/portfolio.csv |
Application inventory |
data/portfolio_results.json |
7R decisions, wave plan, team requirements, effort estimates |
data/discovery_results.json |
Auto-discovered applications from org scans |
data/approvals.jsonl |
Approval requests and reviews |
data/agent_runs.jsonl |
Pipeline execution history (or agent_runs table in PostgreSQL) |
data/llm_logs/{task_id}.json |
Full LLM message exchanges per pipeline run (or llm_message_logs table) |
data/pm_tracking.json |
Manual app/wave migration status |
data/pm_reports.json |
Cached PM status reports |
data/learning_insights.json |
Learning agent findings |
data/ingestion.json |
Source code ingestion metadata |
data/repos/{app_id}/ |
Ingested source code files |
data/security_scan_{app_id}.json |
Security scan results per app |
data/compliance_{app_id}.json |
Compliance assessment results per app |
data/remediation/{app_id}.json |
Remediation plan with code changes |
data/settings.json |
Model and integration settings |
Run the test suite:
pytest tests/ -v
All 117 tests cover authentication, data ingestion, models, PM dashboard, and web routes.
- Portfolio: Replace sample CSV with your CMDB export
- Rules: Adjust 7R scoring thresholds in agent prompts
- Discovery: Integrate outputs from Migration Evaluator, CloudMapper, or AWS Application Insights
- Model: Change the Claude model via Settings page or
REFACTORIUM_MODELenvironment variable - Auth: Extend with OAuth/SSO for enterprise deployments
See ROADMAP.md for planned features and enhancements.
- User Guide — Detailed walkthrough of the web application
- Roadmap — Planned features and enhancements
Version: 1.4 Last Updated: February 2026 Platform: Refactorium