Architecture Overview · AWS Reference Deployment · Solution Design

Software Factory — AWS Reference Architecture

A two-phase, LLM-driven modernization pipeline: a 6R/7R rationalization engine scores a legacy application portfolio, and for every app recommended Refactor, Rehost, or Relocate, an orchestrated, human-in-the-loop factory pipeline discovers, assesses, generates code for, tests, security-scans, and produces IaC for a modernized version. This page documents the design as it exists in the codebase today — including a working reference deployment on EKS — not a proposed target.

EKS + Bedrock · Working Reference2 HITL Gates · LangGraph OrchestratedInternal Tooling · Not Customer-Facing

Reviewed against the actual codebase — backend, frontend, rationalization engine, shared schema, and existing Terraform — not an aspirational diagram. Governance Scanner and MemoryOS integration are explicitly unfinished; the wiki store is a temporary placeholder.

Phase 1
Rationalization Engine
Batch/CLI pipeline. Given a CSV inventory of legacy applications (e.g. an RVTools export), 6 LLM agents plus a 22-rule deterministic validator produce a per-app 6R/7R recommendation (Retain / Repurchase / Retire / Refactor / Rehost / Relocate / Replatform) with TCO/ROI financial modeling and a confidence score.
6 LLM agents + 22-rule validator
Phase 2
Factory Backend
Flask + LangGraph state machine. For apps scored Refactor/Rehost/Relocate, orchestrates a 12-stage per-app pipeline with 2 human approval gates, streaming progress to a React frontend over Server-Sent Events.
LangGraph · SSE streaming
Factory Pipeline — 12 Stages, 2 Human-in-the-Loop Gates
Stage 1
Discovery
Reads legacy app source (incl. sample-apps for testing); runs in parallel across apps/languages via thread pool.
›
Stage 2
Rationalization
Confirms/refines the Phase 1 6R/7R score in pipeline context.
›
Stage 3
Supervisor Routing
Low-confidence scores route to Gate 1; high-confidence scores proceed straight to Requirements.
›
Gate 1
HITL — App Decision
Interrupt via interrupt(), resumed by /api/decide. Pipeline can pause indefinitely.
Stage 4
Requirements
Generates the modernization build spec the code stage will target.
›
Gate 2
HITL — Requirements Approval
Resumed via /api/approve-reqs. Second hard stop before any code is generated.
›
Stage 5
Coding
kiro-cli subprocess generates modernized code against the approved build spec.
›
Stage 6
Test Writing
Generates the test suite for the newly written code.
Stage 7
Testing
Executes the generated test suite; runs in parallel across apps/languages.
›
Stage 8
Security Scan
Bandit static-analysis scan of generated code before it can advance.
›
Stage 9 · ≤3 retries
Quality Gate
On failure, loops back to Coding — up to 3 retries per app — before falling through to Audit as blocked.
›
Stage 10–11
IaC Generation → Audit
Passing builds generate IaC, then every path (pass or blocked) converges on a final audit record.
🔒
Governance & Human-in-the-Loop Design
Two hard-stop approval gates — not advisory checkpoints. LangGraph checkpoints every step to Postgres, so a run can sit paused indefinitely awaiting a human without losing state. Generated code is scanned (bandit) and quality-gated with a bounded retry loop before it's allowed to produce IaC. Multi-tenant by design: every request is org/project-scoped, with LangGraph thread IDs of the form pipeline-<orgId>-<projectId>.
2 hard HITL gatesBandit security scanQuality gate, ≤3 retriesOrg/project-scoped multi-tenancyCheckpointed pause/resume
Component
Frontend
React SPA, 5 tabs (Pipeline, Coordinators, Sandbox, Wiki, Architecture) plus the HITL approval UI. Entra ID (Azure AD) auth via MSAL.
CloudFront + S3
Component
Shared State Schema
UnifiedAppState — the typed contract handed from Phase 1 rationalization scoring to the Phase 2 factory pipeline.
shared/unified_state.py
Component
Wiki Store (Temporary)
Postgres metadata + S3 artifacts. Explicitly frozen, not to be extended further — a placeholder pending a future MemoryOS integration.
Not extended further
Component
Sample Apps
14 small (100–10K LOC) synthetic legacy codebases used as pipeline test input. No separate AWS footprint — just files read at Discovery.
14 apps · test input only
12
Pipeline stages
2
Hard HITL approval gates
≤3
Quality-gate retries per app
14
Sample legacy apps for testing
💰
Cost to Operate
Bedrock invocation volume — not infrastructure — is the primary cost driver. Roughly 6–10 LLM calls per application scored in rationalization, plus 1 call per factory-pipeline node that generates content, with up to 3 retries through the coding → testing → quality-gate loop per app. The EKS + RDS + ALB + NAT infrastructure footprint is a fixed, moderate baseline regardless of pipeline usage — the reference deployment runs a single backend replica and a 2-node (min)/6-node (max) Graviton EKS node group.
Primary cost: Bedrock, not infrat4g.xlarge Graviton, 2–6 nodesSingle RDS instance, 2 logical DBsApplication Inference Profiles recommended
AWS Services (Reference Deployment)EKS (Graviton, t4g.xlarge)RDS PostgreSQL 16S3 ×3 (frontend / wikistore / kiro-config)ECRCloudFrontALB + AWS LB ControllerRoute53 + ACMSecrets ManagerBedrock (Claude Sonnet 4.5)VPC, 3 AZ
External Dependencies (Non-AWS)kiro-cli (subprocess)Microsoft Entra ID (JWT auth)GitHub / GitLab (PAT)Optional: Azure OpenAI / direct Anthropic API
Known gaps before the reference IaC is portable to a new account: this Terraform is a working reference from a prior environment, not a neutral starting template.
  • Hardcoded ownership/identity: tags, Entra tenant/client IDs, and the Route53 zone default are specific to the prior environment and need re-parameterizing.
  • Inconsistent RDS sizing/HA found between Terraform files (instance class and Multi-AZ setting disagree) — needs a single source of truth before sizing a new environment.
  • EKS may be more than this single workload needs — one Deployment, one Service, one Job. Worth a deliberate decision vs. ECS Fargate or App Runner.
  • Governance Scanner and MemoryOS integration are explicitly unfinished per the project's own README — the wiki store and related state fields are placeholders, not live integrations.
  • SCM PAT provisioning is out-of-band — populated by the backend at runtime, not by Terraform, so it needs an operational runbook rather than pure IaC.