# deepractice/promptx architecture

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

- Interactive diagram: https://gitdiagram.com/deepractice/promptx
- Repository: https://github.com/deepractice/promptx

## Overview

##### Project type and purpose
- PromptX is an open-source, file-based prompt-engineering framework (a library/tool), not a client/server web app.
- Its purpose is to provide a structured, modular way to build and manage AI prompts (“DPML” protocol, roles, thought/execution/memory modules).

##### File structure
- Top-level files:
- bootstrap.md – the entry point (system prompt template)
- promptx.js – the loader/initializer script
- core/ – core engine modules (execution pipeline & memory pipeline)
- domain/ – built-in roles (assistant, copywriter, prompt-developer, scrum, test) each with subfolders: role, thought, execution, practice
- protocol/ – DPML language definitions and tag semantics
- resource/ – common resource descriptions (execution, memory, thought)
- assets/ – demo images, docs
- Pattern: file-based plugin architecture. Markdown files define behavior, loaded at runtime by promptx.js.
- No database or network service; state is persisted to a .memory directory.

##### Extract insights from README
- Workflow:
1. Copy PromptX into a host project
2. Edit bootstrap.md to reference one or more domain role files
3. Invoke promptx.js (or copy bootstrap.md into your AI system)
4. The AI engine uses DPML protocol to orchestrate Thought → Execution → Memory cycles
- Key features: Thought, Execution, Memory modules; built-in roles; DPML protocol.

- Client / Host Application – invokes the loader or pastes system prompt
- Loader (promptx.js) – reads bootstrap.md, resolves @file:// URIs, assembles the system prompt
- File Module Repository
– Core Modules (core/execution, core/memory)
– Domain Modules (domain/*)
– Protocol Definitions (protocol/*.protocol.md, protocol/tag/*.tag.md)
– Resources (resource/*.resource.md)
- AI Engine – receives assembled prompt, runs DPML-driven pipeline
- Memory Store – file-based .memory folder for read/write
- User Interaction / Output
1. Host App → Loader: “load bootstrap.md”
2. Loader → File Repo: “fetch & parse modules”
3. Loader → AI Engine: “deliver system prompt (DPML)”
4. AI Engine ↔ Memory Store: “recall & store memories”
5. AI Engine → Output → Host App or user
c. Architectural patterns & design principles:
– Modular plugin architecture (each role/thought/execution/memory unit is a Markdown plugin)
– Separation of concerns:
- Protocol (DPML)
- Thought → Execution → Memory pipelines
- Domain-specific roles
– File-first configuration, no hardcoded code modules
d. Key technologies/frameworks:
– Node.js (promptx.js loader)
– Markdown as DSL for DPML
– Custom DPML protocol definitions (in protocol/…)
– File-system persistence for memory

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Layer
    subgraph "Host Application"
        HostApp["Host App"]:::host
        bootstrap["bootstrap.md"]:::entry
    end

    %% Loader Layer
    promptx["promptx.js"]:::loader

    %% File Module Repository
    subgraph "File Module Repository"
        subgraph "Core Modules"
            core_exec["core/execution"]:::core
            core_mem["core/memory"]:::core
        end
        subgraph "Domain Modules"
            domain_dir["domain"]:::domain
        end
        subgraph "Protocol Definitions"
            protocol_dir["protocol"]:::protocol
        end
        subgraph "Resource Definitions"
            resource_dir["resource"]:::resource
        end
    end

    %% AI Engine and Memory
    subgraph "AI Engine"
        AIEngine["AI Engine\n(DPML Pipeline)"]:::engine
    end
    memoryStore[".memory (Memory Store)"]:::storage
    output["User Interaction / Output"]:::output

    %% Connections
    HostApp -->|load bootstrap.md| bootstrap
    bootstrap -->|invoke| promptx
    promptx -->|fetch & parse modules| core_exec
    promptx --> core_mem
    promptx --> domain_dir
    promptx --> protocol_dir
    promptx --> resource_dir
    promptx -->|deliver system prompt| AIEngine
    AIEngine -->|store memories| memoryStore
    AIEngine -->|recall memories| memoryStore
    AIEngine -->|generate response| output
    output --> HostApp

    %% Click Events
    click bootstrap "https://github.com/deepractice/promptx/blob/main/bootstrap.md"
    click promptx "https://github.com/deepractice/promptx/blob/main/promptx.js"
    click core_exec "https://github.com/deepractice/promptx/tree/main/core/execution"
    click core_mem "https://github.com/deepractice/promptx/tree/main/core/memory"
    click domain_dir "https://github.com/deepractice/promptx/tree/main/domain"
    click protocol_dir "https://github.com/deepractice/promptx/tree/main/protocol"
    click resource_dir "https://github.com/deepractice/promptx/tree/main/resource"

    %% Styles
    classDef host fill:#f4f4f4,stroke:#333,stroke-width:1px;
    classDef entry fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef loader fill:#a8d0e6,stroke:#333,stroke-width:1px;
    classDef core fill:#74b9ff,stroke:#333,stroke-width:1px;
    classDef domain fill:#55efc4,stroke:#333,stroke-width:1px;
    classDef protocol fill:#fdcb6e,stroke:#333,stroke-width:1px;
    classDef resource fill:#ffeaa7,stroke:#333,stroke-width:1px;
    classDef engine fill:#fd79a8,stroke:#333,stroke-width:1px;
    classDef storage fill:#dfe6e9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef output fill:#fab1a0,stroke:#333,stroke-width:1px;
```
