# fintan-contents/promptis architecture

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

- Interactive diagram: https://gitdiagram.com/fintan-contents/promptis
- Repository: https://github.com/fintan-contents/promptis

## Overview

##### Main Components
- VS Code Host & Extension Host
- Extension Activation Module (extension.ts)
- Command Dispatcher & ChatHandler (chatHandler.ts)
- Prompt Loader & Utilities (chatutil.ts, util.ts)
- Configuration Manager (config.ts)
- OpenAPI-generated Chat API Client (src/openapi + api.ts)
- Prompt Repository (prompts/*.md)
- Build & Packaging Toolchain (esbuild.js, package.json, .devcontainer)
- CI/CD & Testing (GitHub workflows, src/test)
- External Services:
– GitHub Copilot Chat Extension / Chat Service API
– Telemetry Server

##### Relationships and Data Flows
- Developer workspace → esbuild → packaged VS Code extension (vsix) → Marketplace/Local install
- GitHub Actions → lint / test / release workflows → artifact publication
1. User types “@promptis /command” in a VS Code editor chat window
2. VS Code Extension Host invokes extension.ts → registers the command
3. Command Dispatcher (chatHandler) loads matching prompt files from the prompts directory via chatutil
4. Configuration Manager supplies paths/filters from config.ts or user settings
5. ChatHandler calls Chat API via api.ts, which uses the OpenAPI client under src/openapi
6. Chat responses flow back into VS Code chat UI
7. Telemetry events collected and sent to the telemetry server (optional)
- Unit tests in src/test cover modules (api.test.ts, chatHandler.test.ts etc.)
- GitHub Actions run tests and coverage reporting

##### Architectural Patterns & Principles
- Modular separation: Activation → Command Handling → Prompt Loading → API Calling → UI Display
- Single-Responsibility:
– extension.ts: registration/activation
– chatHandler.ts: orchestration of commands
– chatutil.ts/util.ts: file I/O, prompt parsing, filtering
– api.ts + OpenAPI client: HTTP client abstraction
- Code Generation: OpenAPI generator produces the client in src/openapi from openapi.yaml
- Configuration-as-Code: user settings align with config.ts defaults
- Test-driven: structured test directory mirrors src modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer and Build Pipeline
    subgraph "Developer / Build" 
        direction TB
        DevWorkspace["Developer Workspace"]:::dev
        Esbuild["esbuild.js"]:::build
        PackageJSON["package.json"]:::build
        DevContainer[".devcontainer/"]:::build
        VSIX["Packaged VS Code Extension (vsix)"]:::build
        DevWorkspace -->|"bundle"| Esbuild
        Esbuild -->|"produces"| VSIX
        PackageJSON --> VSIX
        DevContainer --> VSIX
        GitHubActions["GitHub Actions Workflows"]:::build
        GitHubActions -->|"lint/test/release"| VSIX
    end

    %% Runtime Extension Host
    subgraph "VS Code Extension Host"
        direction TB
        Activation["Extension Activation Module\n(extension.ts)"]:::ext
        CommandDispatcher["Command Dispatcher & ChatHandler\n(chatHandler.ts)"]:::ext
        PromptLoader["Prompt Loader & Utilities\n(chatutil.ts)"]:::ext
        Util["Utility Functions\n(util.ts)"]:::ext
        ConfigManager["Configuration Manager\n(config.ts)"]:::ext
        PromptRepo["Prompt Repository\n(prompts/*.md)"]:::ext
        APIWrapper["API Wrapper\n(api.ts)"]:::ext
        OpenAPIClient["OpenAPI Client\n(src/openapi/)"]:::ext

        Activation -->|"registers command"| CommandDispatcher
        CommandDispatcher -->|"loads prompts"| PromptLoader
        PromptLoader --> PromptRepo
        CommandDispatcher -->|"gets config"| ConfigManager
        CommandDispatcher -->|"calls"| APIWrapper
        APIWrapper --> OpenAPIClient
        APIWrapper -->|"HTTP POST"| ChatAPI
        ChatAPI -->|"response"| CommandDispatcher
        CommandDispatcher -->|"sends telemetry"| Telemetry
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ChatAPI["GitHub Copilot Chat Service API"]:::external
        Telemetry["Telemetry Server"]:::external
    end

    %% Testing & QA
    subgraph "Testing & QA"
        direction TB
        TestSuite["Test Suite\n(src/test/)"]:::test
        TestSuite -->|"covers modules"| Activation
        TestSuite --> CommandDispatcher
        GitHubActions -->|"runs tests"| TestSuite
    end

    %% Runtime Flow from User
    User["User in VS Code Chat UI"]:::user
    User -->|"@promptis /command"| Activation

    %% Click Events
    click Activation "https://github.com/fintan-contents/promptis/blob/main/src/extension.ts"
    click CommandDispatcher "https://github.com/fintan-contents/promptis/blob/main/src/chatHandler.ts"
    click PromptLoader "https://github.com/fintan-contents/promptis/blob/main/src/chatutil.ts"
    click Util "https://github.com/fintan-contents/promptis/blob/main/src/util.ts"
    click ConfigManager "https://github.com/fintan-contents/promptis/blob/main/src/config.ts"
    click OpenAPIClient "https://github.com/fintan-contents/promptis/tree/main/src/openapi/"
    click APIWrapper "https://github.com/fintan-contents/promptis/blob/main/src/api.ts"
    click PromptRepo "https://github.com/fintan-contents/promptis/tree/main/prompts/"
    click Esbuild "https://github.com/fintan-contents/promptis/blob/main/esbuild.js"
    click PackageJSON "https://github.com/fintan-contents/promptis/blob/main/package.json"
    click DevContainer "https://github.com/fintan-contents/promptis/tree/main/.devcontainer/"
    click GitHubActions "https://github.com/fintan-contents/promptis/tree/main/.github/workflows/"
    click TestSuite "https://github.com/fintan-contents/promptis/tree/main/src/test/"

    %% Styles
    classDef dev fill:#f9f,stroke:#333,stroke-width:1px
    classDef build fill:#ddd,stroke:#333,stroke-width:1px
    classDef ext fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#bfb,stroke:#333,stroke-width:1px
    classDef test fill:#feb,stroke:#333,stroke-width:1px
    classDef user fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
