# nicknochnack/mcpin10 architecture

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

- Interactive diagram: https://gitdiagram.com/nicknochnack/mcpin10
- Repository: https://github.com/nicknochnack/mcpin10

## Overview

##### Project type and purpose
- This is a lightweight microservice-style Python application (“MCP Server”) whose goal is to ingest and serve financial ticker data (e.g. from Yahoo Finance) and to integrate with an LLM workflow via Ollama and Langflow.
- The two runtime components are:
- server.py – the “inspector” or API server that exposes endpoints for managing and querying ticker data.
- agent.py – the background agent that fetches raw ticker data from external sources and writes it into the local ticker_db.

##### File structure
- Top‐level files:
- pyproject.toml – dependency manifest (Uvicorn, FastAPI or similar, ticker‐db driver).
- server.py – starts the MCP API.
- agent.py – polling/fetching service.
- Directory ticker_db/ holds persistent storage:
- A per‐ticker GUID folder with binary data files (data_level0.bin, header.bin, etc.) and a pickled index.
- chroma.sqlite3 – an embedded vector‐index database for similarity search (used by your LLM workflows).
- .python-version, .gitignore, uv.lock, .venv – environment and tooling files for uv (your CLI wrapper).

##### README for additional insights
- Steps call out two processes (mcp dev server.py and agent.py) plus a separate Langflow UI that plugs into Ollama.
- External requirement: an Ollama LLM daemon must be running to process embeddings or LLM calls.

##### Components and interactions
a. Main components:
- API Server (server.py + Uvicorn/FastAPI)
- Agent Worker (agent.py)
- Persistent storage:
– Ticker_DB (binary files + index)
– Chroma SQLite vector DB
- External Data Source: Yahoo Finance (or any other data provider)
- LLM Service: Ollama (local LLM runtime)
- Orchestration/UI: Langflow (optional front‐end that talks to the API server or directly to LLM)
b. Relationships & data flows:
1. Agent → External Data Source: fetch latest ticker quotes.
2. Agent → Ticker_DB: write raw binary data + update index.
3. API Server ←→ Ticker_DB & Chroma DB:
– Read requests for historical/similarity queries.
4. API Server → Ollama: for any LLM/embedding requests (via vector index or prompt).
5. Langflow UI → API Server or Ollama directly: for user‐driven LLM workflows.
c. Architectural patterns & design principles:
- Separation of concerns: ingestion agent vs. API server.
- Event‐driven or polling model in the agent.
- Repository pattern encapsulated by ticker_db folder and chroma.sqlite3.
- Microservice‐like processes communicating via REST or RPC.
d. Key technologies/frameworks/libraries:
- Python 3.x, Uvicorn (CLI “uv run”), FastAPI or similar.
- Custom binary ticker_db format + pickle metadata.
- SQLite (Chroma vector store) for similarity search.
- Ollama for LLM runtime; Langflow for GUI orchestration.
- uv (poetry/pipenv‐like CLI wrapper) for environment management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion Layer
    subgraph "Ingestion Layer"
        Agent["Agent Worker"]:::service
    end

    %% Serving Layer
    subgraph "Serving Layer"
        API_Server["API Server"]:::service
        Ticker_DB["Ticker_DB"]:::storage
        Chroma["Chroma SQLite Vector DB"]:::storage
        GUID["6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72"]:::storage
        data0["data_level0.bin"]:::storage
        header["header.bin"]:::storage
        meta["index_metadata.pickle"]:::storage
        length["length.bin"]:::storage
        links["link_lists.bin"]:::storage
    end

    %% LLM Layer
    subgraph "LLM Layer"
        Ollama["Ollama LLM Service"]:::external
        Langflow["Langflow UI"]:::external
    end

    %% External Data Source
    Yahoo["Yahoo Finance"]:::external

    %% Data Flows
    Agent -->|"1. Fetch (HTTP/REST)"| Yahoo
    Agent -->|"2. Write (File I/O)"| Ticker_DB
    API_Server -->|"3. Read/Write (File I/O)"| Ticker_DB
    API_Server -->|"3. Read/Write (SQL)"| Chroma
    API_Server -->|"4. LLM Calls (HTTP/REST)"| Ollama
    Langflow -->|"5. User Requests (HTTP/REST)"| API_Server
    Langflow -->|"5. Direct LLM (HTTP/REST)"| Ollama

    %% Internal DB Structure
    Ticker_DB --> GUID
    GUID --> data0
    GUID --> header
    GUID --> meta
    GUID --> length
    GUID --> links

    %% Click Events
    click API_Server "https://github.com/nicknochnack/mcpin10/blob/main/server.py"
    click Agent "https://github.com/nicknochnack/mcpin10/blob/main/agent.py"
    click Ticker_DB "https://github.com/nicknochnack/mcpin10/tree/main/ticker_db/"
    click GUID "https://github.com/nicknochnack/mcpin10/tree/main/ticker_db/6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72/"
    click data0 "https://github.com/nicknochnack/mcpin10/blob/main/ticker_db/6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72/data_level0.bin"
    click header "https://github.com/nicknochnack/mcpin10/blob/main/ticker_db/6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72/header.bin"
    click meta "https://github.com/nicknochnack/mcpin10/blob/main/ticker_db/6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72/index_metadata.pickle"
    click length "https://github.com/nicknochnack/mcpin10/blob/main/ticker_db/6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72/length.bin"
    click links "https://github.com/nicknochnack/mcpin10/blob/main/ticker_db/6bf5ae30-4cfe-4e16-8ceb-dc08a0b6cd72/link_lists.bin"
    click Chroma "https://github.com/nicknochnack/mcpin10/blob/main/ticker_db/chroma.sqlite3"
    click pyproject "https://github.com/nicknochnack/mcpin10/blob/main/pyproject.toml"
    click uvlock "https://github.com/nicknochnack/mcpin10/blob/main/uv.lock"
    click pythonver "https://github.com/nicknochnack/mcpin10/blob/main/.python-version"
    click gitignore "https://github.com/nicknochnack/mcpin10/blob/main/.gitignore"

    %% Styles
    classDef service fill:#ADD8E6,stroke:#0000FF,color:#000;
    classDef storage fill:#90EE90,stroke:#008000,color:#000;
    classDef external fill:#FFA500,stroke:#FF4500,color:#000;
```
