# craigomatic/worddoc-aiplugin architecture

> Architecture diagram of the GitHub repository craigomatic/worddoc-aiplugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/craigomatic/worddoc-aiplugin
- Repository: https://github.com/craigomatic/worddoc-aiplugin

## Overview

This repository is a small .NET plugin service whose job is to create Word documents and append content to them. The architecture is centered around a serverless-style HTTP endpoint layer plus a document-writing helper, rather than a traditional app with UI or database.

1. **Runtime / hosting model**
   - The presence of `host.json`, `local.settings.json`, and `Program.cs` strongly suggests an Azure Functions-style .NET host.
   - `worddoc-aiplugin.csproj` defines the app as a single deployable service, likely containerless/serverless.

2. **Public integration surface**
   - `PluginEndpoint.cs` is the outward-facing API boundary.
   - This is the component other systems call to invoke document actions such as creating a new Word document or appending text/content.

3. **Plugin metadata / contract**
   - `Model/AIPlugin.cs` likely represents the plugin definition or tool metadata exposed to an AI orchestration layer.
   - It probably describes the operations the plugin supports, enabling an LLM or agent framework to discover and call them.

4. **Request model boundary**
   - `Model/AppendToDocRequest.cs` captures the input contract for append operations.
   - This separates transport concerns from document logic and makes the endpoint shape explicit.

5. **Configuration boundary**
   - `Model/ModelConfig.cs` holds runtime settings used by the plugin and writer.
   - In this repo, configuration is likely used to control document location, storage settings, or other environment-dependent values loaded from app settings.

6. **Document generation core**
   - `WordDocWriter.cs` is the main internal service responsible for Word document creation and mutation.
   - It is the core business logic boundary: endpoints call into it, and it handles the actual document update behavior.

7. **Data flow**
   - A caller sends a plugin request to `PluginEndpoint`.
   - The request is mapped into a model such as `AppendToDocRequest`.
   - The endpoint delegates to `WordDocWriter`.
   - The writer produces or updates the document and returns success/identity details back through the endpoint.

8. **Storage / external dependency**
   - The README notes it works best with `azblob-aiplugin`, which implies this plugin is designed to pair with blob storage for reading/writing document files.
   - So the document itself is probably stored externally rather than kept in memory or a local database.

9. **Operational configuration**
   - `local.settings.json` is for local development environment variables.
   - `host.json` controls host-level runtime behavior, reinforcing that this is deployed and operated as a hosted function/service.

10. **System boundary summary**
   - This repo contains one focused service boundary: “AI-callable Word document operations.”
   - Everything inside it supports that purpose: endpoint entry, request models, config, and document-writing implementation.

Main entry points: [`PluginEndpoint.cs`](https://github.com/craigomatic/worddoc-aiplugin/blob/main/PluginEndpoint.cs) (Plugin endpoint), [`WordDocWriter.cs`](https://github.com/craigomatic/worddoc-aiplugin/blob/main/WordDocWriter.cs) (Word writer), [`Program.cs`](https://github.com/craigomatic/worddoc-aiplugin/blob/main/Program.cs) (Program), [`Model/AIPlugin.cs`](https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/AIPlugin.cs) (Plugin contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_program["Program<br/>host bootstrap<br/>[Program.cs]"]
  node_host_json["Host config<br/>host settings<br/>[host.json]"]
  node_local_settings["Local settings<br/>env config"]
  node_project["Project file<br/>deployable svc"]
end

subgraph group_api["API Surface"]
  node_endpoint["Plugin endpoint<br/>HTTP endpoint<br/>[PluginEndpoint.cs]"]
end

subgraph group_models["Contracts"]
  node_ai_plugin["Plugin contract<br/>tool metadata<br/>[AIPlugin.cs]"]
  node_append_request["Append request<br/>input model"]
  node_model_config["Model config<br/>runtime config<br/>[ModelConfig.cs]"]
end

subgraph group_core["Document Core"]
  node_writer["Word writer<br/>doc service<br/>[WordDocWriter.cs]"]
  node_blob_storage[("Blob storage<br/>external storage")]
  node_word_doc["Word document<br/>output artifact"]
end

node_program -->|"hosts"| node_endpoint
node_host_json -.->|"configures"| node_program
node_local_settings -.->|"env"| node_program
node_project -.->|"builds"| node_program
node_endpoint -->|"exposes"| node_ai_plugin
node_endpoint -->|"accepts"| node_append_request
node_endpoint -->|"delegates"| node_writer
node_writer -.->|"reads"| node_model_config
node_writer -->|"persists"| node_blob_storage
node_writer -->|"creates"| node_word_doc
node_append_request -.->|"drives"| node_writer
node_ai_plugin -.->|"describes"| node_endpoint

click node_program "https://github.com/craigomatic/worddoc-aiplugin/blob/main/Program.cs"
click node_host_json "https://github.com/craigomatic/worddoc-aiplugin/blob/main/host.json"
click node_local_settings "https://github.com/craigomatic/worddoc-aiplugin/blob/main/local.settings.json"
click node_project "https://github.com/craigomatic/worddoc-aiplugin/blob/main/worddoc-aiplugin.csproj"
click node_endpoint "https://github.com/craigomatic/worddoc-aiplugin/blob/main/PluginEndpoint.cs"
click node_ai_plugin "https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/AIPlugin.cs"
click node_append_request "https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/AppendToDocRequest.cs"
click node_model_config "https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/ModelConfig.cs"
click node_writer "https://github.com/craigomatic/worddoc-aiplugin/blob/main/WordDocWriter.cs"

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_program,node_host_json,node_local_settings,node_project toneBlue
class node_endpoint toneAmber
class node_ai_plugin,node_append_request,node_model_config toneMint
class node_writer,node_blob_storage,node_word_doc toneRose
```

## Components

### Runtime

Azure Functions-style hosting and deployment entry points.

- [Program](https://github.com/craigomatic/worddoc-aiplugin/blob/main/Program.cs): host bootstrap · Wires up the function host and service dependencies. · `Program.cs`
- [Host config](https://github.com/craigomatic/worddoc-aiplugin/blob/main/host.json): host settings · Function host configuration and runtime behavior. · `host.json`
- [Local settings](https://github.com/craigomatic/worddoc-aiplugin/blob/main/local.settings.json): env config · Local development environment variables and secrets. · `local.settings.json`
- [Project file](https://github.com/craigomatic/worddoc-aiplugin/blob/main/worddoc-aiplugin.csproj): deployable svc · Single deployable .NET service definition and package references. · `worddoc-aiplugin.csproj`

### API Surface

External invocation boundary for plugin actions.

- [Plugin endpoint](https://github.com/craigomatic/worddoc-aiplugin/blob/main/PluginEndpoint.cs): HTTP endpoint · Public API boundary for invoking document operations. · `PluginEndpoint.cs`

### Contracts

Plugin metadata, request shapes, and runtime settings.

- [Plugin contract](https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/AIPlugin.cs): tool metadata · Describes the plugin surface exposed to an AI orchestrator. · `Model/AIPlugin.cs`
- [Append request](https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/AppendToDocRequest.cs): input model · Input contract for appending content to a document. · `Model/AppendToDocRequest.cs`
- [Model config](https://github.com/craigomatic/worddoc-aiplugin/blob/main/Model/ModelConfig.cs): runtime config · Configuration values consumed by the plugin and writer. · `Model/ModelConfig.cs`

### Document Core

Word document creation and append behavior.

- [Word writer](https://github.com/craigomatic/worddoc-aiplugin/blob/main/WordDocWriter.cs): doc service · Core service that creates and mutates Word documents. · `WordDocWriter.cs`
- **Blob storage**: external storage · External file store used to persist document assets.
- **Word document**: output artifact · The generated or updated document produced by the service.

## Connections

- Program → Plugin endpoint: hosts · Bootstraps the HTTP/function entry point.
- Host config → Program: configures · Supplies host-level runtime behavior.
- Local settings → Program: env · Provides local environment settings during development.
- Project file → Program: builds · Defines the service and its dependencies.
- Plugin endpoint → Plugin contract: exposes · Publishes the plugin contract for discovery.
- Plugin endpoint → Append request: accepts · Parses append operation input.
- Plugin endpoint → Word writer: delegates · Routes document actions to the writer service.
- Word writer → Model config: reads · Uses runtime settings to control document behavior.
- Word writer → Blob storage: persists · Reads and writes document content via external storage.
- Word writer → Word document: creates · Produces or updates the Word document artifact.
- Append request → Word writer: drives · Supplies append parameters into document logic.
- Plugin contract → Plugin endpoint: describes · Maps supported operations to the callable endpoint.