# harshcodespaces/maptocode architecture

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

- Interactive diagram: https://gitdiagram.com/harshcodespaces/maptocode
- Repository: https://github.com/harshcodespaces/maptocode

## Overview

MapToCode is a browser-based algorithm-learning workspace: users edit an algorithm specification or flowchart, reconcile and validate project representations, generate code, and inspect a step-by-step trace. The workspace also supports project management, examples, file-oriented editing, and a FastAPI execution boundary. The graph reflects excerpted calls and README-described capabilities; some UI panels and execution details were not sampled, so uncertain internal links are omitted.

Main entry points: [`components/workspace/WorkspaceClient.tsx`](https://github.com/harshcodespaces/maptocode/blob/main/components/workspace/WorkspaceClient.tsx) (Workspace controller), [`components/workspace/IdeWorkspace.tsx`](https://github.com/harshcodespaces/maptocode/blob/main/components/workspace/IdeWorkspace.tsx) (IDE workspace), [`core/generation-gate.js`](https://github.com/harshcodespaces/maptocode/blob/main/core/generation-gate.js) (Generation gate), [`core/trace-engine.js`](https://github.com/harshcodespaces/maptocode/blob/main/core/trace-engine.js) (Trace engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and workspace"]
  node_home["Homepage<br/>[page.tsx]"]
  node_workspace_route["Workspace route<br/>[page.tsx]"]
  node_workspace["Workspace controller"]
  node_ide["IDE workspace<br/>[IdeWorkspace.tsx]"]
end

subgraph group_model["Algorithm modeling"]
  node_project_store[("Project store<br/>[project-service.js]")]
  node_workspace_files[("Workspace files<br/>[workspace-files.js]")]
  node_project_examples["Project examples<br/>[examples.js]"]
  node_contract_types["Project and AST models<br/>[contracts.ts]"]
  node_pseudocode_parser["Pseudocode parser"]
  node_flowchart_canvas["Flowchart editor<br/>[FlowCanvas.tsx]"]
  node_ast_adapter["Flowchart and AST adapter<br/>[adapters.js]"]
end

subgraph group_generation["Validation and generation"]
  node_reconciliation["Representation reconciliation<br/>[reconciliation.js]"]
  node_reconciliation_sync["Specification sync"]
  node_validation["AST validation<br/>[ast-validation.js]"]
  node_generation_gate["Generation gate<br/>[generation-gate.js]"]
  node_c_generator["C generator<br/>[c-generator.js]"]
  node_python_generator["Python generator"]
  node_java_generator["Java generator<br/>[java-generator.js]"]
end

subgraph group_learning["Learning and execution"]
  node_trace_engine["Trace engine<br/>[trace-engine.js]"]
  node_logic_tracer["Logic tracer<br/>[LogicTracer.tsx]"]
  node_flowchart_explanation["Flowchart explanation"]
  node_api_client["FastAPI client<br/>[client.ts]"]
  node_execute_route["Execution endpoint<br/>[route.ts]"]
end

node_learner(("Learner"))
node_fastapi{{"FastAPI service"}}

node_learner -->|"opens"| node_home
node_learner -->|"enters"| node_workspace_route
node_workspace_route -->|"renders"| node_ide
node_workspace -->|"loads example"| node_project_examples
node_workspace -->|"syncs specification"| node_reconciliation_sync
node_ide -->|"loads and saves"| node_workspace_files
node_ide -->|"parses pseudocode"| node_pseudocode_parser
node_ide -->|"adapts flowchart"| node_ast_adapter
node_ide -->|"explains flowchart"| node_flowchart_explanation
node_workspace -->|"manages projects"| node_project_store
node_workspace -->|"adapts representations"| node_ast_adapter
node_workspace -->|"checks consistency"| node_reconciliation
node_workspace -->|"checks generation"| node_generation_gate
node_generation_gate -->|"validates AST"| node_validation
node_generation_gate -->|"generates C"| node_c_generator
node_generation_gate -->|"generates Python"| node_python_generator
node_workspace -->|"generates Java"| node_java_generator
node_workspace -->|"shows trace"| node_logic_tracer
node_logic_tracer -->|"runs trace"| node_trace_engine
node_trace_engine -->|"validates AST"| node_validation
node_trace_engine -->|"maps source lines"| node_c_generator
node_trace_engine -->|"maps source lines"| node_python_generator
node_logic_tracer -->|"previews C"| node_c_generator
node_logic_tracer -->|"previews Python"| node_python_generator
node_learner -.->|"requests execution"| node_api_client
node_api_client -->|"sends API requests"| node_fastapi
node_execute_route -.->|"forwards execution"| node_fastapi

click node_home "https://github.com/harshcodespaces/maptocode/blob/main/app/page.tsx"
click node_workspace_route "https://github.com/harshcodespaces/maptocode/blob/main/app/workspace/page.tsx"
click node_workspace "https://github.com/harshcodespaces/maptocode/blob/main/components/workspace/WorkspaceClient.tsx"
click node_ide "https://github.com/harshcodespaces/maptocode/blob/main/components/workspace/IdeWorkspace.tsx"
click node_project_store "https://github.com/harshcodespaces/maptocode/blob/main/core/project-service.js"
click node_workspace_files "https://github.com/harshcodespaces/maptocode/blob/main/core/workspace-files.js"
click node_project_examples "https://github.com/harshcodespaces/maptocode/blob/main/core/examples.js"
click node_contract_types "https://github.com/harshcodespaces/maptocode/blob/main/types/contracts.ts"
click node_pseudocode_parser "https://github.com/harshcodespaces/maptocode/blob/main/core/pseudocode-parser.js"
click node_flowchart_canvas "https://github.com/harshcodespaces/maptocode/blob/main/components/canvas/FlowCanvas.tsx"
click node_ast_adapter "https://github.com/harshcodespaces/maptocode/blob/main/core/adapters.js"
click node_reconciliation "https://github.com/harshcodespaces/maptocode/blob/main/core/reconciliation.js"
click node_reconciliation_sync "https://github.com/harshcodespaces/maptocode/blob/main/core/reconciliation-sync.js"
click node_validation "https://github.com/harshcodespaces/maptocode/blob/main/core/ast-validation.js"
click node_generation_gate "https://github.com/harshcodespaces/maptocode/blob/main/core/generation-gate.js"
click node_c_generator "https://github.com/harshcodespaces/maptocode/blob/main/core/c-generator.js"
click node_python_generator "https://github.com/harshcodespaces/maptocode/blob/main/core/python-generator.js"
click node_java_generator "https://github.com/harshcodespaces/maptocode/blob/main/core/java-generator.js"
click node_trace_engine "https://github.com/harshcodespaces/maptocode/blob/main/core/trace-engine.js"
click node_logic_tracer "https://github.com/harshcodespaces/maptocode/blob/main/components/tracer/LogicTracer.tsx"
click node_flowchart_explanation "https://github.com/harshcodespaces/maptocode/blob/main/core/flowchart-explanation.js"
click node_api_client "https://github.com/harshcodespaces/maptocode/blob/main/api/client.ts"
click node_execute_route "https://github.com/harshcodespaces/maptocode/blob/main/app/api/execute/route.ts"

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_home,node_workspace_route,node_workspace,node_ide toneBlue
class node_project_store,node_workspace_files,node_project_examples,node_contract_types,node_pseudocode_parser,node_flowchart_canvas,node_ast_adapter toneAmber
class node_reconciliation,node_reconciliation_sync,node_validation,node_generation_gate,node_c_generator,node_python_generator,node_java_generator,node_fastapi toneMint
class node_trace_engine,node_logic_tracer,node_flowchart_explanation,node_api_client,node_execute_route toneRose
class node_learner toneIndigo
```

## Components

### App and workspace

- [Homepage](https://github.com/harshcodespaces/maptocode/blob/main/app/page.tsx): `app/page.tsx`
- [Workspace route](https://github.com/harshcodespaces/maptocode/blob/main/app/workspace/page.tsx): `app/workspace/page.tsx`
- [Workspace controller](https://github.com/harshcodespaces/maptocode/blob/main/components/workspace/WorkspaceClient.tsx): `components/workspace/WorkspaceClient.tsx`
- [IDE workspace](https://github.com/harshcodespaces/maptocode/blob/main/components/workspace/IdeWorkspace.tsx): `components/workspace/IdeWorkspace.tsx`

### Algorithm modeling

- [Project store](https://github.com/harshcodespaces/maptocode/blob/main/core/project-service.js): `core/project-service.js`
- [Workspace files](https://github.com/harshcodespaces/maptocode/blob/main/core/workspace-files.js): `core/workspace-files.js`
- [Project examples](https://github.com/harshcodespaces/maptocode/blob/main/core/examples.js): `core/examples.js`
- [Project and AST models](https://github.com/harshcodespaces/maptocode/blob/main/types/contracts.ts): `types/contracts.ts`
- [Pseudocode parser](https://github.com/harshcodespaces/maptocode/blob/main/core/pseudocode-parser.js): `core/pseudocode-parser.js`
- [Flowchart editor](https://github.com/harshcodespaces/maptocode/blob/main/components/canvas/FlowCanvas.tsx): `components/canvas/FlowCanvas.tsx`
- [Flowchart and AST adapter](https://github.com/harshcodespaces/maptocode/blob/main/core/adapters.js): `core/adapters.js`

### Validation and generation

- [Representation reconciliation](https://github.com/harshcodespaces/maptocode/blob/main/core/reconciliation.js): `core/reconciliation.js`
- [Specification sync](https://github.com/harshcodespaces/maptocode/blob/main/core/reconciliation-sync.js): `core/reconciliation-sync.js`
- [AST validation](https://github.com/harshcodespaces/maptocode/blob/main/core/ast-validation.js): `core/ast-validation.js`
- [Generation gate](https://github.com/harshcodespaces/maptocode/blob/main/core/generation-gate.js): `core/generation-gate.js`
- [C generator](https://github.com/harshcodespaces/maptocode/blob/main/core/c-generator.js): `core/c-generator.js`
- [Python generator](https://github.com/harshcodespaces/maptocode/blob/main/core/python-generator.js): `core/python-generator.js`
- [Java generator](https://github.com/harshcodespaces/maptocode/blob/main/core/java-generator.js): `core/java-generator.js`

### Learning and execution

- [Trace engine](https://github.com/harshcodespaces/maptocode/blob/main/core/trace-engine.js): `core/trace-engine.js`
- [Logic tracer](https://github.com/harshcodespaces/maptocode/blob/main/components/tracer/LogicTracer.tsx): `components/tracer/LogicTracer.tsx`
- [Flowchart explanation](https://github.com/harshcodespaces/maptocode/blob/main/core/flowchart-explanation.js): `core/flowchart-explanation.js`
- [FastAPI client](https://github.com/harshcodespaces/maptocode/blob/main/api/client.ts): `api/client.ts`
- [Execution endpoint](https://github.com/harshcodespaces/maptocode/blob/main/app/api/execute/route.ts): `app/api/execute/route.ts`

### Other components

- **Learner**
- **FastAPI service**

## Connections

- Learner → Homepage: opens (evidence: `app/page.tsx`)
- Learner → Workspace route: enters (evidence: `app/workspace/page.tsx`)
- Workspace route → IDE workspace: renders (evidence: `app/workspace/page.tsx`)
- Workspace controller → Project examples: loads example (evidence: `components/workspace/WorkspaceClient.tsx`)
- Workspace controller → Specification sync: syncs specification (evidence: `components/workspace/WorkspaceClient.tsx`)
- IDE workspace → Workspace files: loads and saves (evidence: `components/workspace/IdeWorkspace.tsx`)
- IDE workspace → Pseudocode parser: parses pseudocode (evidence: `components/workspace/IdeWorkspace.tsx`)
- IDE workspace → Flowchart and AST adapter: adapts flowchart (evidence: `components/workspace/IdeWorkspace.tsx`)
- IDE workspace → Flowchart explanation: explains flowchart (evidence: `components/workspace/IdeWorkspace.tsx`)
- Workspace controller → Project store: manages projects (evidence: `components/workspace/WorkspaceClient.tsx`)
- Workspace controller → Flowchart and AST adapter: adapts representations (evidence: `components/workspace/WorkspaceClient.tsx`)
- Workspace controller → Representation reconciliation: checks consistency (evidence: `components/workspace/WorkspaceClient.tsx`)
- Workspace controller → Generation gate: checks generation (evidence: `components/workspace/WorkspaceClient.tsx`)
- Generation gate → AST validation: validates AST (evidence: `core/generation-gate.js`)
- Generation gate → C generator: generates C (evidence: `core/generation-gate.js`)
- Generation gate → Python generator: generates Python (evidence: `core/generation-gate.js`)
- Workspace controller → Java generator: generates Java
- Workspace controller → Logic tracer: shows trace (evidence: `components/workspace/WorkspaceClient.tsx`)
- Logic tracer → Trace engine: runs trace (evidence: `components/tracer/LogicTracer.tsx`)
- Trace engine → AST validation: validates AST (evidence: `core/trace-engine.js`)
- Trace engine → C generator: maps source lines (evidence: `core/trace-engine.js`)
- Trace engine → Python generator: maps source lines (evidence: `core/trace-engine.js`)
- Logic tracer → C generator: previews C (evidence: `components/tracer/LogicTracer.tsx`)
- Logic tracer → Python generator: previews Python (evidence: `components/tracer/LogicTracer.tsx`)
- Learner → FastAPI client: requests execution
- FastAPI client → FastAPI service: sends API requests (evidence: `api/client.ts`)
- Execution endpoint → FastAPI service: forwards execution
