PlanToCode
Back to Documentation
Overview

System Overview

A concise map of the system, the core loop, and the required dependencies.

•
15 min read
•

PlanToCode is a desktop workspace that plans and validates code changes before execution. It coordinates a local Rust job engine, a React UI, and a server proxy for LLM calls. The system follows an offline-first architecture where the desktop app operates independently using SQLite for local state, while the server handles authentication, LLM provider routing, and billing. Without external LLM providers configured with your API keys, the planning and analysis pipelines will not run.

System map

Map of the desktop app, the Rust core, local SQLite storage, and the server proxy.

PlanToCode system map diagram
Click to expand
Four-layer architecture with data flowing down and events streaming back up.

Core loop in practice

  1. Capture the task from text, voice transcription (via useVoiceTranscription hook), or video recording analysis.
  2. Refine the task description and objectives with text_improvement jobs through TextImprovementProcessor.
  3. Run the file discovery workflow: RootFolderSelectionProcessor selects directories, RegexFileFilterProcessor applies patterns, FileRelevanceAssessmentProcessor scores contents, ExtendedPathFinderProcessor expands context.
  4. Generate implementation plans via ImplementationPlanProcessor, which streams XML-formatted plans to the Monaco viewer.
  5. Optionally merge multiple plan drafts with ImplementationPlanMergeProcessor using XML-tagged source plans.
  6. Execute or export the approved plan through PTY terminal sessions or copy-button templates for external agents.
  7. Persist every job, artifact, and terminal log to SQLite (background_jobs, terminal_sessions tables) for auditability.

Major components

  • Desktop UI (React) in desktop/src/ with Monaco plan views, terminal panels, and providers (SessionProvider, TextImprovementProvider).
  • Rust core (Tauri v2) in desktop/src-tauri/ handling commands, jobs, and persistence with capability-based permissions.
  • Local SQLite schema in desktop/src-tauri/migrations/consolidated_schema.sql with WAL mode for concurrent access.
  • Server proxy (Actix-Web) in server/src/ for auth, provider routing, streaming responses, and billing via Stripe.
  • Mobile iOS client in mobile/ios/Core/ with SwiftUI interface, Auth0 PKCE, and WebSocket device linking.
  • Infrastructure automation in infrastructure/ansible/ for Hetzner (EU) and InterServer (US) dedicated servers.

Required dependencies

  • External LLM providers (OpenAI, Anthropic, Google, X.AI, OpenRouter) for plan generation, transcription, and analysis.
  • Auth0-based authentication with PKCE flow for desktop and mobile sessions.
  • PostgreSQL 17 and Redis 7+ for server-side user accounts, billing state, and job queues (self-hosted deployments).
  • Local filesystem access via git ls-files or directory traversal for file discovery workflows.
  • Whisper-compatible transcription endpoint for voice input processing.

Where the behavior lives in the repo

  • Tauri commands: desktop/src-tauri/src/commands/ (35+ command modules: job_commands.rs, workflow_commands.rs, terminal_commands.rs, session_commands.rs, auth0_commands.rs)
  • Workflow orchestration: desktop/src-tauri/src/jobs/workflow_orchestrator/ (definition_loader.rs, stage_scheduler.rs, event_emitter.rs, payload_builder.rs)
  • Job processors: desktop/src-tauri/src/jobs/processors/ (implementation_plan_processor.rs, text_improvement_processor.rs, root_folder_selection_processor.rs)
  • SQLite repositories: desktop/src-tauri/src/db_utils/ (background_job_repository/, session_repository.rs, terminal_repository.rs)
  • Server routes: server/src/routes.rs (configure_routes, configure_public_auth_routes, configure_webhook_routes)
  • LLM proxy handlers: server/src/handlers/proxy_handlers.rs and server/src/handlers/proxy/ (router.rs, providers/)
  • Provider transformers: server/src/handlers/provider_transformers/ (openai.rs, google.rs, anthropic.rs, xai.rs)
  • iOS workflows: mobile/ios/Core/Sources/Workflows/WorkflowManager.swift with MobileSessionManager and APIClient
  • Infrastructure playbooks: infrastructure/ansible/site-base.yml (hardening, PostgreSQL, Redis) and site-app.yml (deployment)

Continue to the runtime walkthrough

See how the core loop executes in practice with detailed job timelines and artifact flows.