# microsoft/poml architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/poml
- Repository: https://github.com/microsoft/poml

## Overview

##### Project Type and Purpose
- This is an open-source, multi-language toolkit (monorepo) for POML, a Prompt Orchestration Markup Language. It includes:
- A core TypeScript/JavaScript SDK and CLI (packages/poml and related packages)
- A Python SDK and CLI (python/poml)
- A Visual Studio Code extension with an LSP server, commands, and a Webview preview (packages/poml-vscode and packages/poml-vscode-webview)
- Documentation site (docs/) and examples (examples/, gallery/)
- CI/CD pipelines (GitHub Actions, Azure Pipelines) for testing, docs, and publishing to npm, PyPI, and the VSCode Marketplace

##### Main Components
- Monorepo Root
- CI/CD config (.github/workflows, azure-pipelines.yml)
- Docs configuration (mkdocs.yml, docs/)
- Shared tooling (bump-version.js, webpack/rollup configs)
- Core SDK (packages/poml)
- Parser/Reader: transforms .poml into in-memory representation
- Writer/Renderer: produces final prompt text (and formats for LLM)
- Components: React-style building blocks (document, table, img, role, task, etc.)
- CLI entry point (cli.ts) for local prompt rendering/testing
- TypeScript Build Package (packages/poml-build)
- Bundles core SDK for distribution via npm
- VSCode Extension (packages/poml-vscode)
- Extension host (extension.ts)
- Commands (addResources, showPreview, showSource, promptGallery, etc.)
- LSP Server (packages/poml-vscode/lsp/server.ts) providing diagnostics, auto-completion, formatting
- Webview Panel (packages/poml-vscode-webview) with React content, state management, scroll sync
- Python SDK (python/poml)
- API modules for parsing, templating, rendering prompts
- CLI entry point (cli.py)
- Integrations (LangChain, MLflow, Weave in python/poml/integration)
- External Services
- LLM Providers (OpenAI, Azure, Google APIs)
- VSCode host

##### Relationships & Data Flows
- Developer → .poml file
- CLI (TS or Python) parses via Reader → builds AST → applies templating → Writer outputs final prompt → sent to LLM API → receives response
- VSCode Extension opens .poml → LSP Server parses & validates → Editor shows diagnostics & auto-completions → “Preview” command sends content to Webview → Webview renders styled prompt
- CI/CD pipelines trigger on commits/PRs → run tests (jest, pytest) → build packages → publish artifacts (npm, PyPI, VSIX)

##### Architectural Patterns & Principles
- Monorepo with multi-package modularization (core SDK, build, extension, webview, Python)
- Plugin architecture for VSCode (commands + LSP + Webview)
- Separation of concerns: core parsing/rendering vs. presentation (Webview CSS-like styles)
- Multi-language SDKs sharing core concepts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root
    subgraph "Monorepo Root"
        CI_WF[".github/workflows"]:::ci_cd
        CI_AZ["azure-pipelines.yml"]:::ci_cd
        DocsConfig["mkdocs.yml"]:::docs
        DocsDir["docs/"]:::docs
        Examples["examples/"]:::docs
        Gallery["gallery/"]:::docs
        Tools["Shared Tooling"]:::core
    end

    %% Core TypeScript SDK
    subgraph "Core SDK (TypeScript)" 
        Parser["Reader/Parser"]:::core
        AST["AST Representation"]:::core
        Writer["Writer/Renderer"]:::core
        Components["Components"]:::core
        TS_CLI["CLI (cli.ts)"]:::core
    end

    %% TypeScript Build Package
    subgraph "TS Build (packages/poml-build)"
        Rollup["rollup.config.js"]:::core
        PKGBuild["package.json"]:::core
    end

    %% Python SDK & CLI
    subgraph "Python SDK" 
        Py_API["API Modules"]:::core
        Py_CLI["CLI (cli.py)"]:::core
        Integrations["Integrations"]:::core
    end

    %% VSCode Extension
    subgraph "VSCode Extension"
        ExtHost["Extension Host (extension.ts)"]:::editor
        Commands["Commands"]:::editor
        LSP["LSP Server"]:::editor
        PanelHost["Webview Panel Host"]:::editor
    end

    %% VSCode Webview UI
    subgraph "VSCode Webview UI"
        WebviewUI["React Webview UI"]:::editor
    end

    %% External Services
    LLM["LLM Providers"]:::external
    VSCodeHost["VSCode Host"]:::external

    %% CI/CD Pipeline Flow
    CI_CD["CI/CD Pipeline"]:::ci_cd
    Tests["Tests (jest, pytest)"]:::ci_cd
    Build["Build Packages"]:::ci_cd
    Publish["Publish Artifacts"]:::ci_cd

    %% Flows
    TS_CLI -->|parse| Parser
    Parser --> AST
    AST -->|render| Writer
    Writer -->|send prompt| LLM

    Py_CLI -->|parse| Parser
    Parser --> AST
    AST -->|render| Writer
    Writer -->|send prompt| LLM

    VSCodeHost -->|open .poml| LSP
    LSP -->|validate| Parser
    Parser -->|diagnostics| LSP
    LSP -->|completions| VSCodeHost

    ExtHost -->|invoke| Commands
    Commands -->|show preview| PanelHost
    PanelHost -->|postMessage| WebviewUI
    WebviewUI -->|render prompt| Writer

    CI_WF --> CI_CD
    CI_AZ --> CI_CD
    CI_CD --> Tests
    Tests --> Build
    Build --> Publish

    %% Click Events
    click CI_WF "https://github.com/microsoft/poml/tree/main/.github/workflows"
    click CI_AZ "https://github.com/microsoft/poml/blob/main/azure-pipelines.yml"
    click DocsConfig "https://github.com/microsoft/poml/blob/main/mkdocs.yml"
    click DocsDir "https://github.com/microsoft/poml/tree/main/docs/"
    click Examples "https://github.com/microsoft/poml/tree/main/examples/"
    click Gallery "https://github.com/microsoft/poml/tree/main/gallery/"
    click Parser "https://github.com/microsoft/poml/tree/main/packages/poml/reader/"
    click Writer "https://github.com/microsoft/poml/blob/main/packages/poml/writer.ts"
    click Components "https://github.com/microsoft/poml/tree/main/packages/poml/components/"
    click TS_CLI "https://github.com/microsoft/poml/blob/main/packages/poml/cli.ts"
    click Rollup "https://github.com/microsoft/poml/blob/main/packages/poml-build/rollup.config.js"
    click PKGBuild "https://github.com/microsoft/poml/blob/main/packages/poml-build/package.json"
    click ExtHost "https://github.com/microsoft/poml/blob/main/packages/poml-vscode/extension.ts"
    click Commands "https://github.com/microsoft/poml/tree/main/packages/poml-vscode/command/"
    click LSP "https://github.com/microsoft/poml/blob/main/packages/poml-vscode/lsp/server.ts"
    click PanelHost "https://github.com/microsoft/poml/tree/main/packages/poml-vscode/panel/"
    click Py_API "https://github.com/microsoft/poml/blob/main/python/poml/api.py"
    click Py_CLI "https://github.com/microsoft/poml/blob/main/python/poml/cli.py"
    click Integrations "https://github.com/microsoft/poml/tree/main/python/poml/integration/"
    click WebviewUI "https://github.com/microsoft/poml/blob/main/packages/poml-vscode-webview/index.ts"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef editor fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ci_cd fill:#FFA500,stroke:#000,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#000,stroke-width:1px
```
