Project Architecture Overview

This page summarizes how the ValorIDE repository is organized and where the extension’s major runtime components live.

Top-Level Layout

Path	Purpose	Notes
assets/	Icons, logos, onboarding imagery consumed by the extension and marketplace listing	Serves both the activity bar (icon.svg) and gallery card art
dist/	Bundled extension output produced by yarn build (dist/extension.js, dist/webview.js)	Published in the .vsix artifacts kept in the repo root
docs/	Developer-facing markdown, ADRs, and MCP tutorials	Mirrors much of what is published to this Docusaurus site
ValorIDE_docs/	End-user docs staged for synchronization with valkyrlabs.com	Contains images, localized copies, and product marketing content
locales/	i18n resources and contributing guides per locale	Powers the multilingual experience in the sidebar webview
src/	Extension runtime written in TypeScript	Hosts activation, task planning, service orchestration, API layers, and CLI integrations
web/	Companion assets for web-targeted builds (ThorAPI outputs, shared UI packages)	Used when ValorIDE bootstraps web projects via ThorAPI
webview-ui/	React 18 webview application rendered inside VS Code	Built with Vite; exports components, hooks, and contexts for the ValorIDE sidebar
out/	Intermediate transpilation output from tsc	Helpful during debugging and unit tests
thorapi/	Placeholder for generated ThorAPI schemas that ValorIDE consumes	Keeps the extension aligned with the Valhalla code generators
valoride-dev-*.vsix	Signed extension packages for manual install and regression testing	Match the version declared in package.json

Runtime Highlights (src/)

• src/extension.ts – activation entry point that wires command registrations, task lifecycle handlers, MCP bootstrap, and telemetry.
• src/api/ – provider adapters for Anthropic, OpenAI, Gemini, Vertex, Bedrock, Mistral, Ollama, and ValkyrAI/ThorAPI endpoints.
• src/core/ & src/services/ – execution loop plumbing: task scheduler, command runner, diff composer, diagnostics ingestion, and approvals management.
• src/tools/ & src/integrations/ – MCP tool definitions, browser automation (Puppeteer, Chrome launcher), terminal management, and peer-to-peer hooks.
• src/shared/ & src/utils/ – common types, logging helpers, token accounting, cost tracking, and configuration management.

Webview Application (webview-ui/)

The sidebar experience is a standalone Vite project (webview-ui/package.json) built with React, Styled Components, Floating UI, and Tailwind v4. It renders task threads, console streams, MCP marketplaces, and account dashboards. Build outputs (HTML, JS, CSS) are emitted into dist/ during the extension build pipeline and referenced by extension.ts.

Build & Tooling

• esbuild.js – composes the extension bundle, resolves path aliases via @esbuild-plugins/tsconfig-paths, and inlines the webview assets.
• vite.config.ts – drives the webview build; referenced by scripts in the root package.json.
• TypeScript configs (tsconfig*.json) – separate configs for extension runtime, unit tests, and integration harnesses.
• test_system.sh / evals/ – harnesses for end-to-end evaluation of ValorIDE tasks.

Entry Points & Execution Flow

1. Activation – VS Code loads dist/extension.js, which resolves back to src/extension.ts sources for maintainers. Activation events include sidebar registration (valoride-dev.SidebarProvider) and command palette entries.
2. Sidebar render – The extension serves the webview-ui bundle into a VS Code webview, enabling React-based task management, MCP browsing, and billing views.
3. Task orchestration – Commands from the UI call into services under src/core/ and src/services/, which coordinate model calls, diff application, shell execution, and approval prompts.
4. ThorAPI/Valhalla integration – When users invoke generation workflows, ValorIDE relies on schemas staged in thorapi/ and calls out to ValkyrAI or ThorAPI backends.

Use this layout as a reference when navigating the repository or extending ValorIDE with new capabilities.