# emoltz/pxt architecture

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

- Interactive diagram: https://gitdiagram.com/emoltz/pxt
- Repository: https://github.com/emoltz/pxt

## Overview

##### Main Architectural Layers and Modules
- Core Engine & Compiler: This layer includes the core libraries and tools such as pxtcompiler (the TypeScript-to-ARM Thumb emitter and transpiler), pxtlib (common functions and APIs), and pxtblocks (the modules that map between blockly and TypeScript). These components handle the language parsing, code conversion, error reporting, and compilation.
- Editor Interfaces: There are multiple front-end “editor” projects built on top of the core engine. Notice directories such as pxteditor, webapp, skillmap, kiosk, multiplayer, teachertool, and tutorialtool. These provide the user-facing block-based (Blockly) as well as text-based (Monaco/VS Code) interfaces.
- Command-Line Interface & Build System: The CLI (found in projects such as “cli” and “pxt-cli”), Gulp build tasks (gulpfile.js, tasks, and Makefile), and scripts form the infrastructure used for building, testing, linking, and serving targets.
- Documentation & Testing: Extensive documentation is located in “docs”, “common-docs”, and “docfiles” while tests reside in the “tests” directory (with subdirectories for compile tests, block tests, language service tests, etc.) to verify the different modules.

##### Data Flow & Interactions
- The CLI and build system trigger the build process, which then compiles user code (in either blocks or text form) using the pxtcompiler and core libraries.
- For editor targets, the user interface (implemented in directories like “webapp”, “skillmap”, “kiosk”, etc.) interacts with both the blockly-based editor (via pxtblocks) and the text-based Monaco editor to provide a seamless programming experience.
- Compiled outputs can be deployed or run directly in the browser (via pxt serve) and sometimes interact with additional services (for authentication in authcode, game hosting in multiplayer or kiosk services, etc.).
- External integrations such as cloud synchronization, GitHub connectivity, and package management are layered on top of core functionality.
- The documentation and tests provide continuous feedback loops so that changes in core libraries or the transpiler are integrated and verified across the ecosystem.

##### Architectural Patterns & Key Principles
- Modularization & Separation of Concerns: The repository is structured into many clearly delineated modules (core engine, front-end editors, CLI, tests, docs) and even different “targets”. This should be captured by grouping these components independently.
- Dependency & Build Pipelines: The build and watch processes (using Gulp and the CLI) are essential in turning changes from source files (mostly in TypeScript) into browser-based experiences – so include these elements in your data flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine & Compiler
    subgraph "Core Engine & Compiler"
        A["pxtcompiler (TypeScript-to-ARM Thumb emitter)"]:::core
        B["pxtlib (Common functions & APIs)"]:::core
        C["pxtblocks (Blockly-to-TypeScript mapper)"]:::core
    end

    %% Editor Interfaces
    subgraph "Editor Interfaces"
        D["pxteditor (Block/Text Editor)"]:::editor
        E["webapp (Web App Interface)"]:::editor
        F["skillmap (Skill Map Interface)"]:::editor
        G["kiosk (Kiosk Interface)"]:::editor
        H["multiplayer (Multiplayer Interface)"]:::editor
        I["teachertool (Teacher Tool)"]:::editor
        J["tutorialtool (Tutorial Tool)"]:::editor
    end

    %% CLI & Build System
    subgraph "CLI & Build System"
        K["cli (Command-line Interface)"]:::cli
        L["pxt-cli (PXT CLI)"]:::cli
        M["gulpfile.js (Gulp Build Task)"]:::cli
        N["Makefile (Make Build File)"]:::cli
    end

    %% Target Integrations
    subgraph "Target Integrations"
        O["pxttarget.json (Target Configuration)"]:::target
        P["theme (Styling & Icons)"]:::target
    end

    %% Documentation & Testing
    subgraph "Documentation & Testing"
        Q["Docs (docs/common-docs/docfiles)"]:::docs
        R["Tests (Test Suite)"]:::docs
    end

    %% Data flow relationships
    K -->|"build"| A
    L -->|"build"| A
    M -->|"build"| A
    N -->|"build"| A

    D -->|"uiInteraction"| C
    E -->|"uiInteraction"| B
    J -->|"uiInteraction"| C

    C -->|"convert"| A
    A -->|"uses"| B

    O -->|"link"| A
    P -->|"link"| B

    R -->|"verify"| A
    Q -->|"feedback"| B

    %% Additional feedback from Core Engine to Editors (compiled output)
    A -->|"deploy"| D
    A -->|"deploy"| E
    A -->|"deploy"| J

    %% Styles
    classDef core fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef editor fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef cli fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef target fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef docs fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;

    %% Click Events for Core Engine & Compiler
    click A "https://github.com/emoltz/pxt/tree/master/pxtcompiler/…"
    click B "https://github.com/emoltz/pxt/tree/master/pxtlib/…"
    click C "https://github.com/emoltz/pxt/tree/master/pxtblocks/…"

    %% Click Events for Editor Interfaces
    click D "https://github.com/emoltz/pxt/tree/master/pxteditor/…"
    click E "https://github.com/emoltz/pxt/tree/master/webapp/…"
    click F "https://github.com/emoltz/pxt/tree/master/skillmap/…"
    click G "https://github.com/emoltz/pxt/tree/master/kiosk/…"
    click H "https://github.com/emoltz/pxt/tree/master/multiplayer/…"
    click I "https://github.com/emoltz/pxt/tree/master/teachertool/…"
    click J "https://github.com/emoltz/pxt/tree/master/tutorialtool/…"

    %% Click Events for CLI & Build System
    click K "https://github.com/emoltz/pxt/tree/master/cli/…"
    click L "https://github.com/emoltz/pxt/tree/master/pxt-cli/…"
    click M "https://github.com/emoltz/pxt/blob/master/gulpfile.js"
    click N "https://github.com/emoltz/pxt/tree/master/Makefile"

    %% Click Events for Target Integrations
    click O "https://github.com/emoltz/pxt/blob/master/pxttarget.json"
    click P "https://github.com/emoltz/pxt/tree/master/theme/…"

    %% Click Events for Documentation & Testing
    click Q "https://github.com/emoltz/pxt/tree/master/docs/"
    click R "https://github.com/emoltz/pxt/tree/master/tests/…"
```
