# pantheralabs/intentcompiler architecture

> Architecture diagram of the GitHub repository pantheralabs/intentcompiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pantheralabs/intentcompiler
- Repository: https://github.com/pantheralabs/intentcompiler

## Overview

1. **What this repository is**
   - Intent Compiler is a fullstack Next.js application that turns a user’s high-level goal into structured AI workflows and instruction files.
   - The core architectural idea is a pipeline: capture intent → enrich context → select models → compile steps/instructions → validate → execute/export.

2. **Primary user entrypoints**
   - `app/page.tsx` is the main intake experience for entering an intent and refining it.
   - `app/workflow/page.tsx` is the interactive execution surface for step-by-step workflow run and review.
   - These pages are supported by reusable UI components in `components/`, especially `ContextForm`, `WorkflowContainer`, `ExecutionPanel`, `InputForm`, and `RepoInput`.

3. **Frontend composition**
   - The UI is a stateful React client built around intent collection, suggestions, workflow visualization, and execution controls.
   - `FileTree`, `HistoryPanel`, `StepCard`, `ModelRecommendationBadge`, and `IntelligentQuestionsModal` represent distinct interaction zones rather than a single monolithic screen.
   - `VibeLibrary` and `WelcomeIntro` add template onboarding and preset browsing for faster workflow creation.

4. **API boundary**
   - The server side is exposed through App Router route handlers under `app/api/*`.
   - Each route isolates a capability: analysis, compilation, generation, execution, validation, suggestions, model selection, and model recommendation.
   - This gives the frontend a set of focused service endpoints instead of a single generic backend.

5. **Intent analysis and context gathering**
   - `app/api/analysis` and `lib/projectAnalyzer.ts` / `lib/repoAnalyzer.ts` detect project characteristics, repo structure, and tech stack.
   - `RepoInput` in the UI likely feeds this path so the system can bootstrap context from an existing repository.
   - `lib/intelligentQuestioner.ts` and `app/api/suggestions` provide targeted clarification when user intent is vague.

6. **Compilation pipeline**
   - The compilation layer is centered in `lib/contextCompiler.ts`, `lib/instructionGenerator.ts`, `lib/instructionAssembler.ts`, and `lib/compile*` API routes.
   - Its job is to transform refined intent into structured plans, step instructions, and instruction-file outputs.
   - The README’s export targets such as `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.windsurfrules` are produced through this path.

7. **Model orchestration and provider abstraction**
   - `lib/aicc.ts`, `lib/modelRouter.ts`, `lib/superIntelligentModel.ts`, and `lib/tierConfig.ts` implement the model-selection layer.
   - The system supports multiple providers and runtimes: OpenAI, OpenRouter, Groq, and local Ollama.
   - Architecturally, this layer sits between product logic and the LLM providers, so task-specific model choice is decoupled from UI and workflow logic.

8. **Multi-agent and role system**
   - `lib/agentOrchestrator.ts`, `lib/dynamicRoles.ts`, `lib/roleMatcher.ts`, `lib/roleDatabase.ts`, and `lib/skillsRegistry.ts` define a specialized agent-coordination subsystem.
   - This is used for more complex generation tasks where the system dispatches work to role-specific agents rather than one general model call.
   - The presence of `multi-agent-generator.js` and test files suggests this path is important for advanced generation scenarios.

9. **Execution and validation loop**
   - `lib/executionEngine.ts`, `lib/validationCheckpoint.ts`, `lib/stepQuality.ts`, and `app/api/execution` form the runtime workflow engine.
   - The architecture supports executing steps individually, validating results, and recovering or rolling back when quality checks fail.
   - This is the “reactive workflow” part of the product: generation is not the end state; generated steps can be run and refined.

10. **Quality gates and scoring**
   - `lib/instructionQuality.ts`, `lib/stepQuality.ts`, and `app/api/validation` provide scoring and validation boundaries.
   - The README describes six evaluation dimensions: correctness, specificity, executability, safety, compatibility, and brevity.
   - In the architecture, this acts as a control layer between generation and execution to keep outputs usable.

11. **Persistence, storage, and logs**
   - `lib/db.ts` with SQLite/better-sqlite3 stores local application state, history, or configuration.
   - `lib/vibeStorage.ts` and `lib/core/vibeStorage.ts` indicate persistence for template or “vibe” assets.
   - `logs/` and `output/` are operational artifacts: logs capture runs and tests, while `output/` stores generated project bundles and prompt files.

12. **Export and artifact generation**
   - `lib/fileExporter.ts` handles packaging outputs such as ZIPs and PDFs, which matches the README’s export-oriented workflow.
   - The checked-in `output/` folder shows the system already materializes full generation runs into structured folders with quickstarts, prompts, and role instructions.
   - This makes the repo both an app and an artifact factory.

13. **Shared schemas and safety**
   - `lib/schemas.ts`, `lib/actionSchemas.ts`, `lib/jsonGuard.ts`, and `lib/core/jsonGuard.ts` provide input/output shaping and JSON resilience.
   - `lib/logger.ts` and `lib/integrationLogger.ts` handle observability around model calls and orchestration.
   - These are important architectural boundaries because almost every API path relies on validated structured data.

14. **Overall system shape**
   - The repository is organized as a pipeline-driven orchestration platform built on Next.js, not just a UI dashboard.
   - Frontend components collect intent and visualize progress; route handlers expose capabilities; `lib/` contains the real domain engine for analysis, compilation, model routing, execution, and validation.
   - For an architecture diagram, the main nodes are: intent intake UI, analysis/suggestion APIs, compilation/orchestration engine, model provider layer, validation/execution engine, local persistence, and generated output artifacts.

Main entry points: [`app/page.tsx`](https://github.com/pantheralabs/intentcompiler/blob/main/app/page.tsx) (Intake page), [`lib/instructionGenerator.ts`](https://github.com/pantheralabs/intentcompiler/blob/main/lib/instructionGenerator.ts) (Instruction pipeline), [`lib/executionEngine.ts`](https://github.com/pantheralabs/intentcompiler/blob/main/lib/executionEngine.ts) (Execution engine), [`lib/instructionQuality.ts`](https://github.com/pantheralabs/intentcompiler/blob/main/lib/instructionQuality.ts) (Quality gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_app_page["Intake page<br/>Next page<br/>[page.tsx]"]
  node_workflow_page["Workflow page<br/>Next page<br/>[page.tsx]"]
  node_context_form["Context form<br/>React component<br/>[ContextForm.tsx]"]
  node_workflow_container["Workflow shell<br/>React component"]
  node_execution_panel["Execution panel<br/>React component<br/>[ExecutionPanel.tsx]"]
  node_repo_input["Repo input<br/>React component<br/>[RepoInput.tsx]"]
  node_questions_modal["Clarification modal<br/>React component"]
  node_vibe_library["Vibe library<br/>React component<br/>[VibeLibrary.tsx]"]
end

subgraph group_api["Service API"]
  node_analysis_api["Analysis API<br/>route handlers<br/>[route.ts]"]
  node_generation_api["Generation API<br/>route handlers<br/>[route.ts]"]
  node_compilation_api["Compilation API<br/>route handlers<br/>[route.ts]"]
  node_execution_api["Execution API<br/>route handlers<br/>[route.ts]"]
  node_validation_api["Validation API<br/>route handlers<br/>[route.ts]"]
  node_model_api["Model APIs<br/>route handlers<br/>[route.ts]"]
end

subgraph group_engine["Core engine"]
  node_project_analyzer{{"Project analysis<br/>repo analysis<br/>[projectAnalyzer.ts]"}}
  node_context_compiler{{"Context compiler<br/>compilation engine<br/>[contextCompiler.ts]"}}
  node_instruction_pipeline{{"Instruction pipeline<br/>instruction generation"}}
  node_model_router{{"Model router<br/>model orchestration<br/>[modelRouter.ts]"}}
  node_agent_orchestrator{{"Agent orchestrator<br/>multi-agent system"}}
  node_execution_engine{{"Execution engine<br/>workflow runtime<br/>[executionEngine.ts]"}}
  node_validation_gate{{"Quality gate<br/>scoring and validation"}}
end

subgraph group_storage["Persistence and outputs"]
  node_db_store[("Local DB<br/>SQLite storage<br/>[db.ts]")]
  node_vibe_storage[("Vibe storage<br/>asset storage<br/>[vibeStorage.ts]")]
  node_file_exporter[("File exporter<br/>artifact packaging<br/>[fileExporter.ts]")]
  node_generated_output["Generated output<br/>artifact folder"]
end

node_app_page -->|"collect intent"| node_context_form
node_app_page -->|"bootstrap repo"| node_repo_input
node_app_page -->|"clarify gaps"| node_questions_modal
node_app_page -->|"browse presets"| node_vibe_library
node_workflow_page -->|"host workflow"| node_workflow_container
node_workflow_container -->|"show steps"| node_execution_panel
node_analysis_api -->|"scan repo"| node_project_analyzer
node_analysis_api -->|"seed context"| node_context_compiler
node_generation_api -->|"dispatch roles"| node_agent_orchestrator
node_generation_api -->|"choose model"| node_model_router
node_compilation_api -->|"build context"| node_context_compiler
node_compilation_api -->|"compile instructions"| node_instruction_pipeline
node_execution_api -->|"run workflow"| node_execution_engine
node_validation_api -->|"score output"| node_validation_gate
node_model_api -->|"select provider"| node_model_router
node_project_analyzer -->|"use model"| node_model_router
node_context_compiler -->|"feed plan"| node_instruction_pipeline
node_instruction_pipeline -->|"verify quality"| node_validation_gate
node_validation_gate -->|"approve run"| node_execution_engine
node_agent_orchestrator -->|"call models"| node_model_router
node_execution_engine -->|"checkpoint"| node_validation_gate
node_db_store -->|"persist state"| node_analysis_api
node_vibe_storage -->|"load presets"| node_vibe_library
node_file_exporter -->|"write artifacts"| node_generated_output
node_instruction_pipeline -->|"export files"| node_file_exporter
node_execution_engine -->|"emit run output"| node_generated_output

click node_app_page "https://github.com/pantheralabs/intentcompiler/blob/main/app/page.tsx"
click node_workflow_page "https://github.com/pantheralabs/intentcompiler/blob/main/app/workflow/page.tsx"
click node_context_form "https://github.com/pantheralabs/intentcompiler/blob/main/components/ContextForm.tsx"
click node_workflow_container "https://github.com/pantheralabs/intentcompiler/blob/main/components/WorkflowContainer.tsx"
click node_execution_panel "https://github.com/pantheralabs/intentcompiler/blob/main/components/ExecutionPanel.tsx"
click node_repo_input "https://github.com/pantheralabs/intentcompiler/blob/main/components/RepoInput.tsx"
click node_questions_modal "https://github.com/pantheralabs/intentcompiler/blob/main/components/IntelligentQuestionsModal.tsx"
click node_vibe_library "https://github.com/pantheralabs/intentcompiler/blob/main/components/VibeLibrary.tsx"
click node_analysis_api "https://github.com/pantheralabs/intentcompiler/blob/main/app/api/analysis/route.ts"
click node_generation_api "https://github.com/pantheralabs/intentcompiler/blob/main/app/api/generation/route.ts"
click node_compilation_api "https://github.com/pantheralabs/intentcompiler/blob/main/app/api/compilation/route.ts"
click node_execution_api "https://github.com/pantheralabs/intentcompiler/blob/main/app/api/execution/route.ts"
click node_validation_api "https://github.com/pantheralabs/intentcompiler/blob/main/app/api/validation/route.ts"
click node_model_api "https://github.com/pantheralabs/intentcompiler/blob/main/app/api/model-selection/route.ts"
click node_project_analyzer "https://github.com/pantheralabs/intentcompiler/blob/main/lib/projectAnalyzer.ts"
click node_context_compiler "https://github.com/pantheralabs/intentcompiler/blob/main/lib/contextCompiler.ts"
click node_instruction_pipeline "https://github.com/pantheralabs/intentcompiler/blob/main/lib/instructionGenerator.ts"
click node_model_router "https://github.com/pantheralabs/intentcompiler/blob/main/lib/modelRouter.ts"
click node_agent_orchestrator "https://github.com/pantheralabs/intentcompiler/blob/main/lib/agentOrchestrator.ts"
click node_execution_engine "https://github.com/pantheralabs/intentcompiler/blob/main/lib/executionEngine.ts"
click node_validation_gate "https://github.com/pantheralabs/intentcompiler/blob/main/lib/instructionQuality.ts"
click node_db_store "https://github.com/pantheralabs/intentcompiler/blob/main/lib/db.ts"
click node_vibe_storage "https://github.com/pantheralabs/intentcompiler/blob/main/lib/vibeStorage.ts"
click node_file_exporter "https://github.com/pantheralabs/intentcompiler/blob/main/lib/fileExporter.ts"
click node_generated_output "https://github.com/pantheralabs/intentcompiler/tree/main/output/2026-03-31_15-13-42_build_a_recipe_app_for_cooking"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_page,node_workflow_page,node_context_form,node_workflow_container,node_execution_panel,node_repo_input,node_questions_modal,node_vibe_library toneBlue
class node_analysis_api,node_generation_api,node_compilation_api,node_execution_api,node_validation_api,node_model_api toneAmber
class node_project_analyzer,node_context_compiler,node_instruction_pipeline,node_model_router,node_agent_orchestrator,node_execution_engine,node_validation_gate toneMint
class node_db_store,node_vibe_storage,node_file_exporter,node_generated_output toneRose
```

## Components

### User experience

Intent intake, workflow review, and reusable interface components.

- [Intake page](https://github.com/pantheralabs/intentcompiler/blob/main/app/page.tsx): Next page · Main intent capture and refinement entrypoint. · `app/page.tsx`
- [Workflow page](https://github.com/pantheralabs/intentcompiler/blob/main/app/workflow/page.tsx): Next page · Interactive workflow execution and review surface. · `app/workflow/page.tsx`
- [Context form](https://github.com/pantheralabs/intentcompiler/blob/main/components/ContextForm.tsx): React component · Collects intent, repo context, and refinement inputs. · `components/ContextForm.tsx`
- [Workflow shell](https://github.com/pantheralabs/intentcompiler/blob/main/components/WorkflowContainer.tsx): React component · Coordinates workflow state and screen composition. · `components/WorkflowContainer.tsx`
- [Execution panel](https://github.com/pantheralabs/intentcompiler/blob/main/components/ExecutionPanel.tsx): React component · Displays step execution controls and results. · `components/ExecutionPanel.tsx`
- [Repo input](https://github.com/pantheralabs/intentcompiler/blob/main/components/RepoInput.tsx): React component · Entry point for analyzing an existing repository. · `components/RepoInput.tsx`
- [Clarification modal](https://github.com/pantheralabs/intentcompiler/blob/main/components/IntelligentQuestionsModal.tsx): React component · Prompts targeted questions when intent is underspecified. · `components/IntelligentQuestionsModal.tsx`
- [Vibe library](https://github.com/pantheralabs/intentcompiler/blob/main/components/VibeLibrary.tsx): React component · Preset and template browser for faster starting points. · `components/VibeLibrary.tsx`

### Service API

App Router endpoints that expose analysis, generation, compilation, validation, and execution capabilities.

- [Analysis API](https://github.com/pantheralabs/intentcompiler/blob/main/app/api/analysis/route.ts): route handlers · Repo scanning and intent-context analysis endpoints. · `app/api/analysis/route.ts`
- [Generation API](https://github.com/pantheralabs/intentcompiler/blob/main/app/api/generation/route.ts): route handlers · Intent refinement and generation orchestration endpoints. · `app/api/generation/route.ts`
- [Compilation API](https://github.com/pantheralabs/intentcompiler/blob/main/app/api/compilation/route.ts): route handlers · Builds context, compiles behavior, and assembles instructions. · `app/api/compilation/route.ts`
- [Execution API](https://github.com/pantheralabs/intentcompiler/blob/main/app/api/execution/route.ts): route handlers · Runs workflow steps and feeds execution state back to the UI. · `app/api/execution/route.ts`
- [Validation API](https://github.com/pantheralabs/intentcompiler/blob/main/app/api/validation/route.ts): route handlers · Checks quality and acceptance of generated or executed output. · `app/api/validation/route.ts`
- [Model APIs](https://github.com/pantheralabs/intentcompiler/blob/main/app/api/model-selection/route.ts): route handlers · Model selection, model listing, and recommendation endpoints. · `app/api/model-selection/route.ts`

### Core engine

Library modules that analyze repos, compile workflows, route models, and run validation/execution.

- [Project analysis](https://github.com/pantheralabs/intentcompiler/blob/main/lib/projectAnalyzer.ts): repo analysis · Detects project structure, tech stack, and repository characteristics. · `lib/projectAnalyzer.ts`
- [Context compiler](https://github.com/pantheralabs/intentcompiler/blob/main/lib/contextCompiler.ts): compilation engine · Transforms analysis and intent into structured workflow context. · `lib/contextCompiler.ts`
- [Instruction pipeline](https://github.com/pantheralabs/intentcompiler/blob/main/lib/instructionGenerator.ts): instruction generation · Generates, assembles, and quality-checks workflow instructions. · `lib/instructionGenerator.ts`
- [Model router](https://github.com/pantheralabs/intentcompiler/blob/main/lib/modelRouter.ts): model orchestration · Selects providers and tiers across OpenAI, OpenRouter, Groq, and Ollama. · `lib/modelRouter.ts`
- [Agent orchestrator](https://github.com/pantheralabs/intentcompiler/blob/main/lib/agentOrchestrator.ts): multi-agent system · Coordinates role-based agents for advanced generation tasks. · `lib/agentOrchestrator.ts`
- [Execution engine](https://github.com/pantheralabs/intentcompiler/blob/main/lib/executionEngine.ts): workflow runtime · Executes steps, manages checkpoints, and supports recovery. · `lib/executionEngine.ts`
- [Quality gate](https://github.com/pantheralabs/intentcompiler/blob/main/lib/instructionQuality.ts): scoring and validation · Scores instructions and step outputs before they progress. · `lib/instructionQuality.ts`

### Persistence and outputs

Local storage, logs, and generated artifacts produced by runs.

- [Local DB](https://github.com/pantheralabs/intentcompiler/blob/main/lib/db.ts): SQLite storage · Stores application state, history, or configuration locally. · `lib/db.ts`
- [Vibe storage](https://github.com/pantheralabs/intentcompiler/blob/main/lib/vibeStorage.ts): asset storage · Persists templates and vibe assets. · `lib/vibeStorage.ts`
- [File exporter](https://github.com/pantheralabs/intentcompiler/blob/main/lib/fileExporter.ts): artifact packaging · Packages generated outputs into downloadable artifacts. · `lib/fileExporter.ts`
- [Generated output](https://github.com/pantheralabs/intentcompiler/tree/main/output/2026-03-31_15-13-42_build_a_recipe_app_for_cooking): artifact folder · Materialized workflow bundles, prompts, quickstarts, and instructions. · `output/2026-03-31_15-13-42_build_a_recipe_app_for_cooking`

## Connections

- Intake page → Context form: collect intent · The intake page is built around the main context form.
- Intake page → Repo input: bootstrap repo · Users can provide a repository to analyze from the intake screen.
- Intake page → Clarification modal: clarify gaps · The UI can ask targeted follow-up questions when intent is vague.
- Intake page → Vibe library: browse presets · Templates and presets help seed a new workflow.
- Workflow page → Workflow shell: host workflow · The workflow page mounts the main orchestration shell.
- Workflow shell → Execution panel: show steps · The container renders step execution and review controls.
- Analysis API → Project analysis: scan repo · API analysis routes rely on repository inspection logic.
- Analysis API → Context compiler: seed context · Analysis results feed the context-building pipeline.
- Generation API → Agent orchestrator: dispatch roles · Generation can fan out to role-specific agents.
- Generation API → Model router: choose model · Generation requests are routed to an appropriate model/provider.
- Compilation API → Context compiler: build context · Compilation routes assemble structured workflow context.
- Compilation API → Instruction pipeline: compile instructions · Compilation routes generate and assemble instruction files.
- Execution API → Execution engine: run workflow · Execution endpoints drive the runtime workflow engine.
- Validation API → Quality gate: score output · Validation endpoints apply quality checks and scoring.
- Model APIs → Model router: select provider · Model endpoints expose routing and recommendation decisions.
- Project analysis → Model router: use model · Analysis and enrichment can depend on model-backed reasoning.
- Context compiler → Instruction pipeline: feed plan · Compiled context becomes the input for instruction generation.
- Instruction pipeline → Quality gate: verify quality · Generated instructions are checked before use.
- Quality gate → Execution engine: approve run · Validated work can move into execution.
- Agent orchestrator → Model router: call models · Agents use the shared provider abstraction.
- Execution engine → Quality gate: checkpoint · Executed steps are validated at checkpoints.
- Local DB → Analysis API: persist state · Local state supports analysis and workflow continuity.
- Vibe storage → Vibe library: load presets · Template assets back the preset browser.
- File exporter → Generated output: write artifacts · Exports materialize into the checked-in output structure.
- Instruction pipeline → File exporter: export files · Compiled instructions can be packaged for download or export.
- Execution engine → Generated output: emit run output · Workflow runs produce concrete artifact folders.
