PlanToCode-Architektur
Wie die Desktop-Shell, Hintergrund-Workflows und gemeinsame Dienste organisiert sind.
PlanToCode ist eine Tauri-Desktop-Anwendung mit einem React-Frontend. Die Benutzeroberfläche rendert Implementierungspläne, Terminals und Konfigurationssteuerungen, während das Rust-Backend Befehle für Workflows, Token-Schätzung und persistente Terminal-Sitzungen bereitstellt. Diese Übersicht fasst zusammen, wie diese Teile zusammenwirken.
System map snapshot
This diagram depicts the PlanToCode system architecture as four interconnected layers arranged vertically. Top Layer - Desktop Frontend: A React/Next.js box containing components (Plan Viewer, Terminal Panel, Session Manager) connected via labeled arrows "invoke()" and "listen()" to the Tauri IPC bridge. Second Layer - Rust Backend: WorkflowOrchestrator (scheduling multi-stage jobs), TerminalSessionManager (PTY lifecycle), and job processors (FileDiscovery, PlanGeneration, TextImprovement, DeepResearch). Third Layer - Persistence: SQLite tables for sessions, background_jobs, and terminal_sessions with read/write arrows. Fourth Layer - External Services: Server routes under /api/llm/* and /api/auth with provider icons (OpenAI, Anthropic, Google, OpenRouter). Data flows run down through the layers; streaming responses and job events flow back up to the UI.
Frontend-Oberfläche
Die Desktop-Benutzeroberfläche ist mit React-Komponenten aufgebaut. Implementierungsplan-Inhalte werden durch einen Monaco-basierten Viewer angezeigt, der große Pläne virtualisiert, Sprachen erkennt und Kopieraktionen unterstützt, damit Prüfer Plan-Text ohne Leistungsprobleme untersuchen können. Terminal-Sitzungen werden in einer gepufferten Ansicht gerendert, die an die PTY-Ausgabe angebunden ist und Verbindungsstatus-Updates anzeigt.
Gemeinsame Provider verwalten Benachrichtigungen, Laufzeitkonfiguration und Plan-Status. Das Implementierungspläne-Panel bewahrt Plan-Metadaten auf, verwaltet die Modal-Sichtbarkeit und fordert Token-Schätzungen oder Prompt-Inhalte bei Bedarf an.
Key React components:
- ImplementationPlansProvider - Plan state and modal management
- PlanViewer (Monaco) - Virtualized plan rendering
- TerminalSurface - PTY output streaming
- TaskDescriptionEditor - Task input with voice integration
- WorkflowTracker - Job progress visualization
Tauri-Befehle und Dienste
Die Rust-Seite der Anwendung stellt Befehle für Workflows, Terminal-Sitzungen und Modell-Werkzeuge bereit. Die Workflow-Befehle starten Hintergrundjobs über den Workflow-Orchestrator, validieren Eingaben und lösen Fortschrittsereignisse aus, während die Dateisuche-Pipeline läuft. Token-Schätzungsbefehle berechnen Prompt-Größen für das aktuell ausgewählte Modell.
Terminal-Befehle verwalten PTY-Prozesse, verfolgen Remote-Clients und überprüfen, ob unterstützte CLI-Binärdateien verfügbar sind, bevor eine Sitzung gestartet wird. Zustandsprüfungen kombinieren den PTY-Status mit Datenbankeinträgen, um zu melden, ob eine Sitzung noch aktiv ist.
Command categories (35+ modules):
- workflow_commands, job_commands - Orchestration
- session_commands, terminal_commands - State management
- implementation_plan_commands - Plan generation
- audio_commands, video_analysis_commands - Media processing
- device_commands, auth0_commands - Connectivity
- config_commands, settings_commands - Configuration
IPC bridge and event streaming
The desktop UI calls Rust commands through the Tauri IPC bridge for workflows, terminal sessions, token estimation, and configuration updates.
Commands are invoked from React and results stream back via event listeners so the UI can update job progress, terminal output, and session state in real time.
IPC event types:
- job:status-changed, job:stream-progress - Job updates
- workflow-status, workflow-stage - Workflow progress
- terminal:output, terminal:status - PTY streaming
- session:updated - Session state changes
- orchestrator:initialized - System ready
Workflow orchestrator
Multi-stage workflows (file discovery, research, plan generation) are defined in JSON and executed by the Workflow Orchestrator.
Each stage maps to a Rust processor; intermediate results are persisted to SQLite and forwarded to the next stage with progress events emitted to the UI.
Workflow definitions:
- file_finder_workflow.json - 4-stage file discovery
- web_search_workflow.json - 2-stage research
- Embedded via embedded_workflows.rs
Persistenz und Konfiguration
Terminal-Ausgaben und Sitzungs-Metadaten werden in SQLite über das Terminal-Sitzungs-Repository gespeichert. Jeder Datensatz enthält Bezeichner, Zeitstempel, Arbeitsverzeichnisse, Umgebungsvariablen und das akkumulierte Protokoll, sodass Neustarts frühere Ausgaben wiederherstellen können. Dasselbe Repository löst Ereignisse aus, wenn sich der Sitzungsstatus ändert.
Modell-Standardwerte befinden sich in der Anwendungskonfigurationstabelle. Jede Aufgabe definiert ein Standardmodell, eine Liste erlaubter Alternativen, Token-Budgets und optionale Kopier-Button-Voreinstellungen. Die React-Schicht liest diese Einstellungen, um den Modell-Selektor und die Leitplanken zu befüllen.
State synchronization
React providers treat SQLite as the source of truth for plans, jobs, and terminal sessions, rehydrating state on startup.
Tauri events update in-memory state as jobs run, while repositories ensure plan history and session output survive restarts.
Sprachtranskriptions-Pipeline
Die Sprachtranskription ist als React-Hook implementiert, der Medienberechtigungen, Mikrofonauswahl und Streaming-Transkriptionsanfragen koordiniert. Der Hook integriert sich mit dem Plan-Terminal und Prompt-Editoren und fügt erkannten Text direkt in die aktive Komponente ein, wobei Benachrichtigungen angezeigt werden, wenn die Transkription fehlschlägt.
Server-Schicht
Der Server verarbeitet Anbieter-Konfiguration (API-Schlüssel im verschlüsselten Tresor, Ratenlimits, Routing-Regeln für OpenAI, Anthropic, Google), Modell-Routing (Anfrage-Proxying, automatisches Failover, Lastverteilung, Kostenverfolgung pro Benutzer/Projekt), Abrechnung (Abonnementverwaltung, Nutzungsmessung, Kontingentdurchsetzung, Kostenwarnungen) und Web-Such-APIs (Ergebnis-Caching mit 30-Tage/7-Tage-TTL, geografische Einschränkungen, JWT-Authentifizierung).
Server components:
- Actix-Web framework with PostgreSQL + Redis
- JWT + API Key authentication with RLS
- LLM proxy: OpenAI, Anthropic, Google, X.AI, OpenRouter
- WebSocket relay for desktop/mobile device linking
- Stripe billing with credit-based usage tracking
Datenflüsse
Aufgaben, Pläne, Jobs und Sitzungen fließen zwischen Komponenten: (1) Aufgabenverfeinerung: React-UI → TextImprovementPopover → Tauri-Befehl → WorkflowOrchestrator → text_improvement Prompt → SQLite → React-Provider ersetzt Text. (2) Dateisuche: Implementierungspläne-Panel → Tauri-Befehl → 4 sequenzielle Jobs → Fortschrittsereignisse → SQLite → UI-Anzeige. (3) Implementierungspläne: Dateisuche → Plan generieren → Tauri-Befehl → LLM-Streaming → SQLite → Monaco-Viewer → Überprüfung/Genehmigung → Export. (4) Terminal-Ausführung: PTY-Sitzung → SQLite → Befehlsausführung → Ausgabe-Streaming → Sprachtranskriptions-Injektion → Agenten-Aufmerksamkeitserkennung → Audit-Protokolle.
LLM routing and provider normalization
Model requests are sent to the server proxy, which routes by provider prefix and normalizes payloads and streaming responses.
The proxy tracks usage, cost, and rate limits per user or project and can fail over across providers when configured.
Key source directories
Desktop (Tauri + React)
- desktop/src - React UI
- desktop/src-tauri/src/commands - IPC commands
- desktop/src-tauri/src/jobs - Job processors
- desktop/src-tauri/src/db_utils - Repositories
- desktop/src-tauri/migrations - SQLite schema
Server (Actix-Web)
- server/src/handlers - Request handlers
- server/src/clients - Provider clients
- server/src/services - Business logic
- server/src/db - PostgreSQL access
- server/src/streaming - SSE adapters
Explore specific subsystems
Dive into the desktop internals, server API, or background jobs to understand each layer in detail.