# sparesparrow/mcp-project-orchestrator architecture

> Architecture diagram of the GitHub repository sparesparrow/mcp-project-orchestrator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sparesparrow/mcp-project-orchestrator
- Repository: https://github.com/sparesparrow/mcp-project-orchestrator

## Overview

#### Purpose and Canonical Surface
This is a Python 3.9+ MCP project-orchestration package: it manages reusable project/component templates and prompts, generates/renders Mermaid diagrams, and exposes MCP/AWS/OpenSSL-oriented orchestration. The primary maintained implementation appears at repository root under `src/`; `mcp-project-orchestrator/` and `restructured/` contain substantial duplicated or reorganized copies.

#### Entry Points and Runtime
CLI/package startup is centered on `src/mcp_project_orchestrator/__main__.py` and `src/mcp_project_orchestrator/cli.py`; MCP server exposure is in `src/mcp_project_orchestrator/server.py`. The runtime is Python, packaged through `pyproject.toml`, with container support in `Containerfile` and a Conan recipe in `conanfile.py`. The advertised executable is `mcp-orchestrator`.

#### Core Orchestration Layer
Shared lifecycle, configuration, manager abstractions, logging, and FastMCP integration are concentrated in:
- `src/mcp_project_orchestrator/core/base.py`
- `src/mcp_project_orchestrator/core/config.py`
- `src/mcp_project_orchestrator/core/managers.py`

CLI/server requests should cross this boundary before invoking template, prompt, diagram, AWS, or specialist orchestration features. Repository-level feature selection/scaffolding is driven by `config/project_orchestration.json`.

#### Template and Project Generation
The template subsystem discovers, validates, renders, and applies project/component definitions:
- `src/mcp_project_orchestrator/templates/manager.py`
- `src/mcp_project_orchestrator/templates/renderer.py`
- `src/mcp_project_orchestrator/templates/project.py`

Templates are JSON assets, including design-pattern component templates under `src/mcp_project_orchestrator/templates/component/` and OpenSSL-consumer scaffolding under `templates/openssl-consumer/`. This is a filesystem-driven generation boundary: inputs are template identifiers plus variables; outputs are generated project files.

#### Prompt and Resource Catalog
Prompt content is versioned as package data and loaded/rendered through a separate management API:
- `src/mcp_project_orchestrator/prompt_manager/loader.py`
- `src/mcp_project_orchestrator/prompt_manager/manager.py`
- `src/mcp_project_orchestrator/prompts/index.json`

The categorized JSON prompt corpus under `src/mcp_project_orchestrator/prompts/` is a primary data asset rather than executable logic. Resources are similarly indexed under `src/mcp_project_orchestrator/resources/index.json`.

#### Diagram Pipeline
Mermaid support is a distinct transformation pipeline:
- `src/mcp_project_orchestrator/mermaid/generator.py`
- `src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py`
- `src/mcp_project_orchestrator/mermaid/renderer.py`

Callers provide graph/diagram intent; the generator produces Mermaid text, orchestration selects templates/options, and the renderer emits artifacts such as SVG/PNG. Diagram templates are stored alongside the code in `src/mcp_project_orchestrator/mermaid/templates/`.

#### External Integrations and Specialized Flows
AWS MCP functionality is isolated in `src/mcp_project_orchestrator/aws_mcp.py`, targeting AWS services named in the README: S3, EC2, Lambda, CloudFormation, and IAM. OpenSSL/FIPS and Cursor deployment flows are exposed through:
- `src/mcp_project_orchestrator/commands/openssl_cli.py`
- `src/mcp_project_orchestrator/openssl_tools_orchestration.py`
- `src/mcp_project_orchestrator/cursor_deployer.py`

Additional operational subprojects are separate deployables, notably the containerized Printcast MCP agent (`printcast-agent/src/mcp_server/main.py`) and AWS SIP/Asterisk infrastructure (`aws-sip-trunk/terraform/main.tf`); they should not be treated as dependencies of the core package without explicit integration wiring.

#### Automation and Repository Boundary
GitHub Actions provide CI/CD, deployment, release, ecosystem monitoring, and fan-out orchestration under `.github/workflows/`. The repository includes many duplicated snapshots and generated/content-heavy directories; new core changes should target `src/mcp_project_orchestrator/`, root packaging metadata, and root tests unless the task explicitly concerns `restructured/` or the nested copy.

Main entry points: [`src/mcp_project_orchestrator/core/managers.py`](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/managers.py) (Manager abstractions), [`src/mcp_project_orchestrator/core/base.py`](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/base.py) (Lifecycle and FastMCP), [`src/mcp_project_orchestrator/templates/manager.py`](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/manager.py) (Template manager), [`src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py`](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py) (Diagram orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core runtime"]
  node_package["Python package<br/>[pyproject.toml]"]
  node_cli["CLI startup<br/>entry point<br/>[cli.py]"]
  node_mcp_server{{"MCP server<br/>[server.py]"}}
  node_core_base["Lifecycle and FastMCP<br/>core layer<br/>[base.py]"]
  node_core_config["Orchestration config<br/>configuration layer<br/>[config.py]"]
  node_core_managers["Manager abstractions<br/>core layer<br/>[managers.py]"]
  node_project_config["Project feature config<br/>JSON configuration"]
  node_template_manager["Template manager<br/>generation service<br/>[manager.py]"]
  node_template_renderer["Template renderer<br/>generation stage<br/>[renderer.py]"]
  node_project_generator["Project generator<br/>generation stage<br/>[project.py]"]
  node_prompt_manager["Prompt manager<br/>catalog service<br/>[manager.py]"]
  node_mermaid_orchestrator["Diagram orchestration<br/>diagram service"]
  node_mermaid_generator["Mermaid generator<br/>transformation stage<br/>[generator.py]"]
  node_mermaid_renderer["Artifact renderer<br/>rendering stage<br/>[renderer.py]"]
  node_aws_mcp{{"AWS MCP integration<br/>cloud integration<br/>[aws_mcp.py]"}}
  node_openssl_flow["OpenSSL/FIPS flow<br/>specialist orchestration"]
  node_cursor_deployer["Cursor deployment<br/>deployment flow<br/>[cursor_deployer.py]"]
end

subgraph group_content["Package content"]
  node_template_assets["Component templates<br/>JSON assets"]
  node_prompt_catalog["Prompt catalog<br/>JSON assets<br/>[index.json]"]
  node_diagram_templates["Diagram templates<br/>template assets"]
end

subgraph group_operations["Operations"]
  node_github_actions["GitHub Actions<br/>automation"]
  node_printcast_agent{{"Printcast MCP agent<br/>separate deployable<br/>[main.py]"}}
  node_sip_infrastructure["AWS SIP infrastructure<br/>Terraform deployable<br/>[main.tf]"]
end

node_package -->|"installs"| node_cli
node_cli -->|"requests"| node_core_base
node_mcp_server -->|"requests"| node_core_base
node_core_base -->|"loads"| node_core_config
node_core_base -->|"uses"| node_core_managers
node_core_config -->|"reads"| node_project_config
node_core_managers -->|"invokes"| node_template_manager
node_core_managers -->|"invokes"| node_prompt_manager
node_core_managers -->|"invokes"| node_mermaid_orchestrator
node_core_managers -->|"invokes"| node_aws_mcp
node_core_managers -->|"invokes"| node_openssl_flow
node_core_managers -->|"invokes"| node_cursor_deployer
node_template_manager -->|"discovers"| node_template_assets
node_template_manager -->|"renders with"| node_template_renderer
node_template_renderer -->|"produces definitions"| node_project_generator
node_prompt_manager -->|"loads"| node_prompt_catalog
node_mermaid_orchestrator -->|"selects"| node_diagram_templates
node_mermaid_orchestrator -->|"directs"| node_mermaid_generator
node_mermaid_generator -->|"Mermaid text"| node_mermaid_renderer
node_github_actions -->|"builds and releases"| node_package
node_github_actions -.->|"deploys independently"| node_printcast_agent
node_github_actions -.->|"automates independently"| node_sip_infrastructure

click node_package "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/pyproject.toml"
click node_cli "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/cli.py"
click node_mcp_server "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/server.py"
click node_core_base "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/base.py"
click node_core_config "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/config.py"
click node_core_managers "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/managers.py"
click node_project_config "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/config/project_orchestration.json"
click node_template_manager "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/manager.py"
click node_template_renderer "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/renderer.py"
click node_project_generator "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/project.py"
click node_prompt_manager "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/prompt_manager/manager.py"
click node_prompt_catalog "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/prompts/index.json"
click node_mermaid_orchestrator "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py"
click node_mermaid_generator "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/generator.py"
click node_mermaid_renderer "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/renderer.py"
click node_aws_mcp "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/aws_mcp.py"
click node_openssl_flow "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/openssl_tools_orchestration.py"
click node_cursor_deployer "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/cursor_deployer.py"
click node_printcast_agent "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/printcast-agent/src/mcp_server/main.py"
click node_sip_infrastructure "https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/aws-sip-trunk/terraform/main.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_cli,node_mcp_server,node_core_base,node_core_config,node_core_managers,node_project_config,node_template_manager,node_template_renderer,node_project_generator,node_prompt_manager,node_mermaid_orchestrator,node_mermaid_generator,node_mermaid_renderer,node_aws_mcp,node_openssl_flow,node_cursor_deployer toneBlue
class node_template_assets,node_prompt_catalog,node_diagram_templates toneAmber
class node_github_actions,node_printcast_agent,node_sip_infrastructure toneMint
```

## Components

### Core runtime

Canonical Python package under src/.

- [Python package](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/pyproject.toml): package · Published as the mcp-orchestrator executable. · `pyproject.toml`
- [CLI startup](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/cli.py): entry point · `src/mcp_project_orchestrator/cli.py`
- [MCP server](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/server.py): server · `src/mcp_project_orchestrator/server.py`
- [Lifecycle and FastMCP](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/base.py): core layer · Shared request boundary, logging, and lifecycle abstractions. · `src/mcp_project_orchestrator/core/base.py`
- [Orchestration config](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/config.py): configuration layer · `src/mcp_project_orchestrator/core/config.py`
- [Manager abstractions](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/core/managers.py): core layer · `src/mcp_project_orchestrator/core/managers.py`
- [Project feature config](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/config/project_orchestration.json): JSON configuration · Drives repository-level feature selection and scaffolding. · `config/project_orchestration.json`
- [Template manager](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/manager.py): generation service · Discovers and validates project and component definitions. · `src/mcp_project_orchestrator/templates/manager.py`
- [Template renderer](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/renderer.py): generation stage · `src/mcp_project_orchestrator/templates/renderer.py`
- [Project generator](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/templates/project.py): generation stage · Applies rendered definitions to generated project files. · `src/mcp_project_orchestrator/templates/project.py`
- [Prompt manager](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/prompt_manager/manager.py): catalog service · Loads and renders versioned prompt content. · `src/mcp_project_orchestrator/prompt_manager/manager.py`
- [Diagram orchestration](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py): diagram service · Selects diagram templates and rendering options. · `src/mcp_project_orchestrator/mermaid/mermaid_orchestrator.py`
- [Mermaid generator](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/generator.py): transformation stage · Converts graph intent into Mermaid text. · `src/mcp_project_orchestrator/mermaid/generator.py`
- [Artifact renderer](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/mermaid/renderer.py): rendering stage · Emits SVG or PNG diagram artifacts. · `src/mcp_project_orchestrator/mermaid/renderer.py`
- [AWS MCP integration](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/aws_mcp.py): cloud integration · Orchestrates S3, EC2, Lambda, CloudFormation, and IAM. · `src/mcp_project_orchestrator/aws_mcp.py`
- [OpenSSL/FIPS flow](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/openssl_tools_orchestration.py): specialist orchestration · `src/mcp_project_orchestrator/openssl_tools_orchestration.py`
- [Cursor deployment](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/cursor_deployer.py): deployment flow · `src/mcp_project_orchestrator/cursor_deployer.py`

### Package content

Versioned template, prompt, and diagram assets.

- **Component templates**: JSON assets
- [Prompt catalog](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/src/mcp_project_orchestrator/prompts/index.json): JSON assets · Categorized prompt corpus indexed as package data. · `src/mcp_project_orchestrator/prompts/index.json`
- **Diagram templates**: template assets

### Operations

External deployment targets and repository automation.

- **GitHub Actions**: automation · CI/CD, release, monitoring, and fan-out workflows.
- [Printcast MCP agent](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/printcast-agent/src/mcp_server/main.py): separate deployable · Containerized operational subproject, not a core dependency. · `printcast-agent/src/mcp_server/main.py`
- [AWS SIP infrastructure](https://github.com/sparesparrow/mcp-project-orchestrator/blob/main/aws-sip-trunk/terraform/main.tf): Terraform deployable · Separate Asterisk/SIP infrastructure subproject. · `aws-sip-trunk/terraform/main.tf`

## Connections

- Python package → CLI startup: installs
- CLI startup → Lifecycle and FastMCP: requests
- MCP server → Lifecycle and FastMCP: requests
- Lifecycle and FastMCP → Orchestration config: loads
- Lifecycle and FastMCP → Manager abstractions: uses
- Orchestration config → Project feature config: reads
- Manager abstractions → Template manager: invokes
- Manager abstractions → Prompt manager: invokes
- Manager abstractions → Diagram orchestration: invokes
- Manager abstractions → AWS MCP integration: invokes
- Manager abstractions → OpenSSL/FIPS flow: invokes
- Manager abstractions → Cursor deployment: invokes
- Template manager → Component templates: discovers
- Template manager → Template renderer: renders with
- Template renderer → Project generator: produces definitions
- Prompt manager → Prompt catalog: loads
- Diagram orchestration → Diagram templates: selects
- Diagram orchestration → Mermaid generator: directs
- Mermaid generator → Artifact renderer: Mermaid text
- GitHub Actions → Python package: builds and releases
- GitHub Actions → Printcast MCP agent: deploys independently
- GitHub Actions → AWS SIP infrastructure: automates independently