VolitionCI Architecture & Reference

1. Overview & Quickstart

VolitionCI is an autonomous DevSecOps and Infrastructure-as-Code generation engine. Rather than relying on brittle single-prompt completions, VolitionCI separates infrastructure authoring into four deterministic stages: Context Ingestion, Architectural Interrogation, Modular ReAct Synthesis, and Self-Healing Verification.

2. Ingestion Workflows

Step 1 of the Studio supports three distinct entry points depending on whether you are starting from greenfield requirements or an existing repository:

3. ReAct Planner-Worker Synthesis Engine

Large cloud architectures regularly exceed single-call output token budgets on high-speed inference providers, causing truncated YAML/HCL files. VolitionCI solves this in `/api/synthesize` via a three-phase streaming architecture:

1. Phase 1 · Modular Infrastructure PlannerEvaluates the repository context and interrogation answers to decompose the target into 2 to 5 ordered modules — for example ["Provider Settings", "Networking", "IAM", "Compute", "Database"].
2. Phase 2 · Context-Chaining Worker LoopIterates sequentially across planned modules. Each Worker invocation receives all previously verified code so resource references (such as aws_vpc.core.id or shared pipeline job names) remain consistent across module boundaries.
3. Phase 3 · Semantic Completeness ValidatorCross-checks the assembled artifact against every user-selected stack component and interrogation answer, flagging any omitted service (`MISSING: <component>`) prior to finalizing delivery.

4. Deterministic Validation & Self-Healing Gate

Every synthesized module is concatenated with prior output and validated before the Worker advances:

• YAML Multi-Document Parsing: Validated through YAML.loadAll() (`js-yaml`), ensuring both single-document CI pipelines and `---`-delimited Kubernetes manifests parse without indentation or anchor errors.
• HCL Structural & Root-Block Audit: Tracks string-literal and escape-aware brace depth while asserting recognizable top-level Terraform declarations (`terraform`, `provider`, `resource`, `variable`, `module`, `output`, `data`).
• Automated 3-Attempt Remediation: When a linter error occurs, the exact diagnostic stack trace is fed back into a dedicated healing prompt for up to 3 automated repair cycles.

5. Zero-Trust Security Baselines

6. Multi-Provider LLM Routing

`runModelChain` executes each role against an ordered provider list, emitting live `usage` SSE telemetry tagged `(Primary)` or `(Fallback N)`:

7. Self-Hosting & Environment Configuration

To run VolitionCI locally or deploy to Vercel, configure the following keys in `.env.local` or your project secret store:

# .env.local
GEMINI_API_KEY="your_google_gemini_api_key"
GROQ_API_KEY="your_groq_api_key"
MISTRAL_API_KEY="your_mistral_codestral_key"
COHERE_API_KEY="your_cohere_api_key"

# Optional: Elevates GitHub REST API rate limits during repository scanning
GITHUB_TOKEN="ghp_optional_personal_access_token"

8. REST & SSE API Reference

curl -X POST https://volition-ci.vercel.app/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/Zomma2/VolitionCI",
    "archetype": "pipeline",
    "targetPlatform": "GitHub Actions"
  }'

event: status
data: {"step":"planning"}

event: usage
data: {"model":"gemini-3.6-flash","role":"Planner (Primary)","usage":{"prompt_tokens":312,"completion_tokens":84,"total_tokens":396}}

event: status
data: {"step":"synthesizing_module","module":"Networking","current":1,"total":4}

event: status
data: {"step":"validating"}

event: status
data: {"step":"semantic_validation"}

event: complete
data: {"code":"terraform {\n  required_version = \">= 1.7.0\"\n..."}