# adrianliechti/wingman architecture

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

- Interactive diagram: https://gitdiagram.com/adrianliechti/wingman
- Repository: https://github.com/adrianliechti/wingman

## Overview

Based on our review of the file tree and README, this project is a full-fledged LLM Platform (also called the Inference Hub) that enables the integration, configuration, and orchestration of a wide variety of LLM providers, vector indexes, document extractors, routers, and custom tools. The platform is intended to simplify development and deployment of large language model applications at scale by providing a unified, modular, and extensible framework.

##### Main Components Identification
- Indexes: Handle data storage, retrieval, and interaction with vector databases. Directories like pkg/index (subfolders for Azure, Chromia, Qdrant, Postgrest, etc.) indicate this.
- Extractors: Components that process and extract information from documents. Look at pkg/extractor (with support for Tika, Unstructured, and other extraction services).
- Segmenters and Summarizers: Responsible for breaking text into manageable chunks (segmentation) and summarizing large texts. These are under pkg/segmenter and pkg/summarizer respectively.
- Routers & Rate Limiters: To distribute incoming requests between multiple providers (e.g., pkg/router/roundrobin, pkg/limiter, etc.).
- Tools: A variety of utilities (crawlers, search, translation, drawing, etc.) reside under pkg/tool.
- API Layers & Server: The cmd and server directories (like cmd/server and server/api) handle HTTP endpoints, request routing, and aggregation of the functionalities.
- Configuration: The config directory shows that the system uses a set of Go configuration files to manage settings for providers, chains, renderers, and more. This is complemented by YAML configuration examples in the README.
- Observability: The pkg/otel folder shows adoption of OpenTelemetry for distributed tracing, logging, and monitoring.

##### Relationships and Interactions
- The server then routes requests to the appropriate components based on the type of request—whether that’s a model call (providers), indexing/search (indexes), data extraction (extractors), or text segmentation/summarization.
- Data/request flow from the API layer to the chain management and then to the underlying providers.
- Requests passing from the routing/load-balancing components to different models/providers.
- Communication between the server and database/vector indexes.
- Interactions for observability services (OpenTelemetry) which monitor multiple components.

##### Architectural Patterns and Design Principles
- Modularity & Extensibility: The architecture is designed to easily plug in new providers, indexes, extractors, and tools—each component is decoupled.
- Provider Abstraction: A unified interface abstracts the diversity of external and local LLM services.
- Configuration-Driven: Emphasize the flexible YAML-based configuration that allows dynamic setup of models and services.
- Microservice-like separation: Though integrated in one repository, the separation into cmd/server, pkg, and server directories suggests a layered architecture similar to microservices or modular monolith patterns.

##### Technologies, Frameworks, and Libraries
- Written in Go, so mention core packages (cmd/, pkg/).
- OpenTelemetry for observability.
- YAML for configuration management.
- Integration with multiple external (and Dockerized) services like Dockerfile-based setups, vector databases (ChromaDB, Qdrant, Weaviate, Elasticsearch), and tools for document extraction and language model interfacing.
- Use of gRPC for custom plugins (noted in the examples and in components such as custom tools).

##### Detail and Clarity
- Data transformation stages (e.g., chain processing in pkg/chain) so that the overall workflow—from request to response—is transparent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client"]:::client
    B["API Server / Gateway"]:::api
    C["Router & Rate Limiter"]:::router
    D["LLM Providers"]:::provider
    E["Indexes / Data Storage"]:::index
    F["Extractors"]:::extractor
    G["Segmenters"]:::segmenter
    H["Summarizers"]:::summarizer
    I["Tools & Utilities"]:::tool
    J["Configuration Manager"]:::config
    K["Observability (OpenTelemetry)"]:::otel

    A -->|"HTTP_Request"| B
    J -->|"initialize"| B
    J -->|"initialize"| D
    B -->|"Routes"| C
    C -->|"Directs"| D
    D -->|"Returns"| B
    B -->|"Index_Query"| E
    E -->|"Returns"| B
    B -->|"Extract_Data"| F
    F -->|"Returns"| B
    B -->|"Segment_Text"| G
    G -->|"Returns"| B
    B -->|"Summarize_Text"| H
    H -->|"Returns"| B
    B -->|"Invoke_Tool"| I
    I -->|"Returns"| B

    K -.->|"Monitors"| B
    K -.->|"Monitors"| D
    K -.->|"Monitors"| E
    K -.->|"Monitors"| F
    K -.->|"Monitors"| G
    K -.->|"Monitors"| H
    K -.->|"Monitors"| I

    %% Click Events
    click B "https://github.com/adrianliechti/wingman/tree/main/cmd/server"
    click D "https://github.com/adrianliechti/wingman/tree/main/pkg/provider"
    click E "https://github.com/adrianliechti/wingman/tree/main/pkg/index"
    click F "https://github.com/adrianliechti/wingman/tree/main/pkg/extractor"
    click G "https://github.com/adrianliechti/wingman/tree/main/pkg/segmenter"
    click H "https://github.com/adrianliechti/wingman/tree/main/pkg/summarizer"
    click C "https://github.com/adrianliechti/wingman/tree/main/pkg/router"
    click I "https://github.com/adrianliechti/wingman/tree/main/pkg/tool"
    click J "https://github.com/adrianliechti/wingman/tree/main/config"
    click K "https://github.com/adrianliechti/wingman/tree/main/pkg/otel"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef router fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef provider fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef index fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef extractor fill:#F08080,stroke:#000,stroke-width:2px;
    classDef segmenter fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef summarizer fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef tool fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef config fill:#F5DEB3,stroke:#000,stroke-width:2px;
    classDef otel fill:#98FB98,stroke:#000,stroke-width:2px;
```
