# sdrshn-nmbr/mc-operator architecture

> Architecture diagram of the GitHub repository sdrshn-nmbr/mc-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sdrshn-nmbr/mc-operator
- Repository: https://github.com/sdrshn-nmbr/mc-operator

## Overview

##### Project Type and Purpose
- This is a backend-focused CLI tool (with optional server and client entry points) for building autonomous web agents. It dynamically generates detailed web-automation prompts from simple user commands using large language models (LLMs) and manages those prompts via templates and a repository.

##### Main Architectural Components
a. Entry Points
- CLI (src/cli.ts) – interactive interface for users to issue commands.
- client.ts / server.ts – optional client/server layer for programmatic access (e.g., via HTTP or other IPC).
b. Agent Layer (src/agent)
- AgentContext – carries state across tasks.
- AgentRunner – orchestrates the high-level flow.
- TaskExecutor – executes individual tasks (calls Prompt generation, LLM, storage, logging).
c. Prompt Management
- PromptGenerator (src/prompt/PromptGenerator.ts) – instantiates templates.
- PromptTemplate (src/prompt/PromptTemplate.ts) – data model for templates.
- Template directories (/templates/system, /templates/tasks, /templates/generated).
d. Storage Layer (src/storage)
- PromptRepository – persists and retrieves generated prompts.
- Underlying storage: local filesystem (./templates/generated) or could extend to DB.
e. Configuration & Settings
- SettingsManager (src/config/SettingsManager.ts) – reads config/settings.json and config/tasks.json.
f. Logging & Analysis
- LogManager (src/logging/LogManager.ts) – collects runtime logs.
- LogAnalyzer (src/logging/LogAnalyzer.ts) – processes and summarizes logs.
g. Utility Components (src/utils)
- LLMClient – wraps calls to external LLM APIs (Anthropic Claude, via ANTHROPIC_API_KEY).
- download-pdf.js – helper script to fetch or save PDFs (supporting media tasks).

##### External Services
- Puppeteer (for web automation – implied by README).
- LLM API endpoint (Anthropic Claude or similar).

##### Relationships and Data Flows
1. User issues command → CLI (or client)
2. CLI forwards to AgentRunner via AgentContext
3. AgentRunner selects TaskExecutor (based on task classification from config/tasks.json)
4. TaskExecutor calls PromptGenerator:
– Merges system prompt (templates/system/*.txt) + task prompt (templates/tasks/*.txt) + variables from user.
5. PromptGenerator returns a formatted prompt → TaskExecutor passes it to LLMClient.
6. LLMClient calls external LLM API and receives detailed instructions.
7. TaskExecutor stores the response in PromptRepository → writes to templates/generated/ or via storage API.
8. TaskExecutor may invoke Puppeteer (download-pdf.js or future agent logic) to enact instructions.
9. LogManager records events; LogAnalyzer can later process them.
10. CLI presents results back to the user.

##### Architectural Patterns & Design Principles
- Layered modular architecture (clear separation: entry, agent, prompt, storage, utils).
- Repository pattern for prompt persistence.
- Template-driven design (system vs. task templates).
- Configuration-driven behavior (config/*.json).
- Single Responsibility (each class handles one concern).

##### Essential Details to Capture
- All major classes (AgentContext, TaskExecutor, PromptGenerator, LLMClient, PromptRepository, SettingsManager, LogManager).
- Data stores (templates/system, templates/tasks, templates/generated).
- External calls (LLM API, Puppeteer browser automation).
- Configuration flow (config/settings.json → SettingsManager → passed to modules).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Entry Points"
        CLI["CLI Interface"]:::core
        Client["Client Entry Point"]:::core
        Server["Server Entry Point"]:::core
    end
    click CLI "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/cli.ts"
    click Client "https://github.com/sdrshn-nmbr/mc-operator/blob/main/client.ts"
    click Server "https://github.com/sdrshn-nmbr/mc-operator/blob/main/server.ts"

    subgraph "Application Logic"
        AgentContext["AgentContext"]:::core
        AgentRunner["AgentRunner"]:::core
        TaskExecutor["TaskExecutor"]:::core
        PromptGenerator["PromptGenerator"]:::core
        PromptTemplate["PromptTemplate"]:::core
        SettingsManager["SettingsManager"]:::core
        LogManager["LogManager"]:::core
        LogAnalyzer["LogAnalyzer"]:::core
        LLMClient["LLMClient"]:::core
        PDFUtil["PDF Download Utility"]:::core
    end
    click AgentContext "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/agent/AgentContext.ts"
    click AgentRunner "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/agent/AgentRunner.ts"
    click TaskExecutor "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/agent/TaskExecutor.ts"
    click PromptGenerator "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/prompt/PromptGenerator.ts"
    click PromptTemplate "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/prompt/PromptTemplate.ts"
    click SettingsManager "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/config/SettingsManager.ts"
    click LogManager "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/logging/LogManager.ts"
    click LogAnalyzer "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/logging/LogAnalyzer.ts"
    click LLMClient "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/utils/LLMClient.ts"
    click PDFUtil "https://github.com/sdrshn-nmbr/mc-operator/blob/main/download-pdf.js"

    subgraph "Local Storage"
        ConfigFiles["Configuration Files"]:::storage
        SysTemplates["System Templates"]:::storage
        TaskTemplates["Task Templates"]:::storage
        GenPrompts["Generated Prompts"]:::storage
        Repo["PromptRepository"]:::core
    end
    click ConfigFiles "https://github.com/sdrshn-nmbr/mc-operator/blob/main/config/settings.json"
    click ConfigFiles "https://github.com/sdrshn-nmbr/mc-operator/blob/main/config/tasks.json"
    click SysTemplates "https://github.com/sdrshn-nmbr/mc-operator/tree/main/templates/system"
    click TaskTemplates "https://github.com/sdrshn-nmbr/mc-operator/tree/main/templates/tasks"
    click GenPrompts "https://github.com/sdrshn-nmbr/mc-operator/tree/main/templates/generated"
    click Repo "https://github.com/sdrshn-nmbr/mc-operator/blob/main/src/storage/PromptRepository.ts"

    subgraph "External Services"
        LLMAPI["LLM API Endpoint"]:::external
        Puppeteer["Puppeteer/Browser"]:::external
    end

    CLI -->|"raw command"| AgentRunner
    Client -->|"raw command"| AgentRunner
    Server -->|"API call"| AgentRunner

    AgentRunner -->|"initializes"| AgentContext
    AgentRunner -->|"selects task"| TaskExecutor
    AgentRunner -->|"loads config"| SettingsManager
    SettingsManager -->|"reads"| ConfigFiles

    TaskExecutor -->|"generate prompt"| PromptGenerator
    PromptGenerator -->|"uses templates"| SysTemplates
    PromptGenerator -->|"uses templates"| TaskTemplates
    PromptGenerator -->|"template model"| PromptTemplate
    PromptGenerator -->|"formatted prompt"| TaskExecutor

    TaskExecutor -->|"invoke LLM"| LLMClient
    LLMClient -->|"API request"| LLMAPI
    LLMAPI -->|"API response"| LLMClient
    LLMClient -->|"LLM response"| TaskExecutor

    TaskExecutor -->|"persist prompt"| Repo
    Repo -->|"write file"| GenPrompts

    TaskExecutor -->|"automation task"| PDFUtil
    TaskExecutor -->|"automation task"| Puppeteer

    TaskExecutor -->|"log event"| LogManager
    LogManager -->|"analyze logs"| LogAnalyzer

    classDef core fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef storage fill:#DFF0D8,stroke:#3C763D,color:#3C763D;
    classDef external fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B;
```
