# michniks2001/poke-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/michniks2001/poke-mcp
- Repository: https://github.com/michniks2001/poke-mcp

## Overview

##### Project type and purpose
- This is a Python-based monolithic service plus CLI tool that provides Pokémon VGC team analysis.
- It exposes two interfaces:
- A “FastMCP” protocol server (RPC style) for integration with MCP-compatible clients.
- A FastAPI REST/web server (with static frontend) for browser-based use and REST clients.

##### Main components
a. Interface layers
- CLI entrypoint (main.py): accepts team files or stdin, calls the core library, prints JSON or text.
- FastMCP server (poke_mcp.server): RPC interface exposing four tools.
- FastAPI web server (poke_mcp.web_server + static/): REST API endpoints + single-page JS frontend.
b. Core library
- parsers (poke_mcp.parsers): Smogon text → Team model
- models (poke_mcp.models): Team, Pokémon data, reports
- analysis (poke_mcp.analysis): damage_calc, speed_tier, strategy_detector, team_analyzer
- services (poke_mcp.services.analysis_pipeline): orchestrates parsing, analysis, threat detection
- clients (poke_mcp.clients): fetch data from external APIs (PokeAPI, Pikalytics)
- LLM adapter (poke_mcp.llm.gemini_client): offload analysis prompts to a language model
- vectorstore (poke_mcp.vectorstore.chroma_store + data/vectorstore): cache embeddings and contexts
c. External systems
- PokeAPI
- Pikalytics
- LLM provider (Google Gemini or another endpoint)

##### Relationships and data flow
- CLI/FastMCP/WebServer → invoke analysis pipeline
→ Parser reads text → Team model
→ services.AnalysisPipeline calls clients & LLM & vectorstore → returns TeamReport
→ Top-level interface serializes to JSON/text/HTTP response
- Clients fetch raw data from external APIs; vectorstore persists embeddings to disk under data/vectorstore.
- WebServer also serves static/index.html + app.js for user input and result rendering.

##### Architectural patterns and design principles
- Layered (Ports & Adapters/Hexagonal): core logic is independent of transport (CLI, RPC, HTTP).
- Single codebase hosting multiple adapters (CLI, RPC, REST).
- Separation of concerns: parsing, domain modeling, analysis, data access, external integrations are in separate packages.
- Cache layer (vectorstore) for expensive LLM embeddings.

##### Technologies & frameworks to annotate
- Python 3 + standard libs
- FastAPI + Uvicorn (web REST server)
- FastMCP (RPC server module)
- Chroma DB (vectorstore)
- HTTP clients for PokeAPI/Pikalytics
- Gemini client (LLM integration)
- pytest for tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interfaces
    CLI["CLI (main.py)"]:::interface
    FastMCP["FastMCP Server (poke_mcp.server)"]:::interface
    REST["REST Server + Web UI (FastAPI + static/)"]:::interface

    %% Static Frontend
    subgraph "Static Frontend" 
        IDX["index.html"]:::interface
        APPJS["app.js"]:::interface
        STYLE["style.css"]:::interface
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Parsers["Parsers\n(smogon.py)"]:::core
        Models["Models\n(team.py)"]:::core
        subgraph "Analysis Modules"
            direction TB
            Damage["damage_calc.py"]:::core
            Speed["speed_tier.py"]:::core
            Strategy["strategy_detector.py"]:::core
            TeamAnal["team_analyzer.py"]:::core
        end
        Services["AnalysisPipeline\n(analysis_pipeline.py)"]:::core
        subgraph "Clients"
            direction TB
            PokeClient["PokeAPI Client\n(pokeapi.py)"]:::core
            PikaClient["Pikalytics Client\n(pikalytics.py)"]:::core
        end
        LLM["LLM Adapter\n(gemini_client.py)"]:::core
        Vectorstore["Vectorstore\n(chroma_store.py)"]:::core
    end

    %% External Services
    PokeAPI["PokeAPI"]:::external
    Pikalytics["Pikalytics API"]:::external
    LLMProv["LLM Provider"]:::external

    %% Storage
    DataStore["Local Vectorstore Files"]:::storage

    %% Connections: Interfaces to Core
    CLI -->|invoke AnalysisPipeline| Services
    FastMCP -->|invoke AnalysisPipeline| Services
    REST -->|POST /api/analyze| Services
    REST -->|serves| IDX
    REST -->|serves| APPJS
    REST -->|serves| STYLE

    %% Analysis flow
    Services -->|parse input| Parsers
    Parsers -->|produce Team model| Models
    Services -->|run analysis| Damage
    Services -->|run analysis| Speed
    Services -->|run analysis| Strategy
    Services -->|run analysis| TeamAnal
    Services -->|fetch data| PokeClient
    Services -->|fetch data| PikaClient
    PokeClient -->|GET species data| PokeAPI
    PikaClient -->|GET stats data| Pikalytics
    Services -->|LLM prompt/response| LLM
    LLM -->|LLM API call| LLMProv
    Services -->|store/read embeddings| Vectorstore
    Vectorstore -->|read/write| DataStore

    %% Return to Interfaces
    Services -->|return TeamReport| CLI
    Services -->|return TeamReport| FastMCP
    Services -->|return JSON| REST

    %% Click Events
    click CLI "https://github.com/michniks2001/poke-mcp/blob/main/main.py"
    click FastMCP "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/server.py"
    click REST "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/web_server.py"
    click IDX "https://github.com/michniks2001/poke-mcp/blob/main/static/index.html"
    click APPJS "https://github.com/michniks2001/poke-mcp/blob/main/static/app.js"
    click STYLE "https://github.com/michniks2001/poke-mcp/blob/main/static/style.css"
    click Parsers "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/parsers/smogon.py"
    click Models "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/models/team.py"
    click Damage "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/analysis/damage_calc.py"
    click Speed "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/analysis/speed_tier.py"
    click Strategy "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/analysis/strategy_detector.py"
    click TeamAnal "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/analysis/team_analyzer.py"
    click Services "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/services/analysis_pipeline.py"
    click PokeClient "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/clients/pokeapi.py"
    click PikaClient "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/clients/pikalytics.py"
    click LLM "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/llm/gemini_client.py"
    click Vectorstore "https://github.com/michniks2001/poke-mcp/blob/main/poke_mcp/vectorstore/chroma_store.py"
    click DataStore "https://github.com/michniks2001/poke-mcp/tree/main/data/vectorstore/"

    %% Styles
    classDef interface fill:#CCE5FF,stroke:#3399FF,color:#000
    classDef core fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef external fill:#FEEFB3,stroke:#9F6000,color:#000
    classDef storage fill:#E0E0E0,stroke:#666666,color:#000
```
