# spoonnotfound/fake-ollama architecture

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

- Interactive diagram: https://gitdiagram.com/spoonnotfound/fake-ollama
- Repository: https://github.com/spoonnotfound/fake-ollama

## Overview

##### Project type and purpose
- From the file tree and README, Fake-Ollama is a lightweight, single‐binary HTTP server written in Go that fully simulates the Ollama API (and OpenAI‐compatible endpoints) for fun or testing. It can run in Docker or as a standalone Go executable.

##### File structure
- Top level:
- `.github/workflows/go.yml` – CI build/test pipeline for Go.
- `Dockerfile` – containerizes the Go server.
- `main.go` – entry point.
- `go.mod` / `go.sum` – dependency management.
- No separate “frontend” or “backend” directories: this is a monolithic service.
- No database or external persistent store; it simulates models in‐memory and streams responses.

##### README for additional insights
- The server listens on `0.0.0.0:11434` by default, configurable via `OLLAMA_HOST`.
- Supports streaming output, multiple “DeepSeek‐R1” model simulations, and both Ollama and OpenAI API endpoints.
- Deployable via Docker or Go build.

a. Main components
- External Clients
- Ollama CLI or SDK
- OpenAI‐compatible clients
- Network Layer
- HTTP/TCP
- Fake‐Ollama Server (monolith)
1) HTTP Listener & Router
2) Request Handlers
– Ollama‐API Handler
– OpenAI‐API Handler
3) Simulation Engine
– DeepSeek‐R1 Model Simulator
– Stream Manager
4) Configuration Module (env var reader)
5) Logging/Telemetry (stdout or container logs)
- Container Runtime (Docker) or Host OS
- (Optional) Reverse Proxy or Load Balancer in front, if deployed in production

b. Relationships and data flow
1) Client → HTTP Listener (port 11434)
2) Router directs to the correct handler (Ollama vs. OpenAI path)
3) Handler invokes Simulation Engine
4) Simulation Engine streams tokens back via Stream Manager
5) HTTP response flows back to Client
6) Configuration Module injects host/port settings at startup
7) Logs emitted to stdout / Docker logs

c. Architectural patterns / design principles
- Single‐process monolith for simplicity
- Handler‐based HTTP routing patterns (Go’s `net/http` mux or similar)
- Pluggable model simulation interfaces (so you could add other “models”)
- Streaming I/O for low‐latency responses

d. Key technologies / libraries
- Go stdlib `net/http` (server, mux, streaming)
- Docker for containerization
- GitHub Actions for CI (`.github/workflows/go.yml`)
- Environment‐based configuration (`OLLAMA_HOST`)

##### Detailed steps
3) Enclose a big boundary named “Fake‐Ollama Container / Host” with:
- HTTP Listener & Router
- Ollama API Handler
- OpenAI API Handler
- DeepSeek‐R1 Simulator
- Stream Manager
- Config & Logging module
5) Off to the side, note the Docker daemon as the runtime and GitHub Actions as CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        CLI["Ollama CLI/SDK"]:::external
        OPENAI["OpenAI-compatible Client"]:::external
    end

    %% Reverse Proxy
    subgraph "Reverse Proxy / Load Balancer"
        PROXY["Reverse Proxy / Load Balancer\n(Port 11434)"]:::external
    end

    CLI -->|"HTTP Request"| PROXY
    OPENAI -->|"HTTP Request"| PROXY

    %% Container Boundary
    subgraph "Fake-Ollama Container / Host"
        direction TB
        LISTENER["HTTP Listener & Router\n(port 11434)"]:::internal
        OLLAMA_HANDLER["Ollama API Handler"]:::internal
        OPENAI_HANDLER["OpenAI API Handler"]:::internal
        SIM_ENGINE["DeepSeek-R1 Model Simulator"]:::internal
        STREAM["Stream Manager"]:::internal
        CONFIG["Configuration Module\n(env reader)"]:::config
        LOGGING["Logging / Telemetry"]:::config

        LISTENER -->|"routes to"| OLLAMA_HANDLER
        LISTENER -->|"routes to"| OPENAI_HANDLER

        OLLAMA_HANDLER -->|"invoke"| SIM_ENGINE
        OPENAI_HANDLER -->|"invoke"| SIM_ENGINE

        SIM_ENGINE -->|"stream tokens"| STREAM

        STREAM -->|"respond"| OLLAMA_HANDLER
        STREAM -->|"respond"| OPENAI_HANDLER

        OLLAMA_HANDLER -->|"HTTP Response"| PROXY
        OPENAI_HANDLER -->|"HTTP Response"| PROXY

        CONFIG --> LISTENER
        CONFIG --> SIM_ENGINE

        LOGGING --> LISTENER
        LOGGING --> SIM_ENGINE
    end

    PROXY -->|"HTTP Response"| CLI
    PROXY -->|"HTTP Response"| OPENAI

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        DOCKER["Docker Container Definition"]:::infra
        CI["CI Build/Test Pipeline"]:::infra
        GOMOD["go.mod"]:::infra
        GOSUM["go.sum"]:::infra
        DOCS["README.md"]:::infra
        LICENSE["LICENSE"]:::infra
        GITIGNORE[".gitignore"]:::infra
    end

    %% Click Events
    click LISTENER "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click OLLAMA_HANDLER "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click OPENAI_HANDLER "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click SIM_ENGINE "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click STREAM "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click CONFIG "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click LOGGING "https://github.com/spoonnotfound/fake-ollama/blob/main/main.go"
    click DOCKER "https://github.com/spoonnotfound/fake-ollama/tree/main/Dockerfile"
    click CI "https://github.com/spoonnotfound/fake-ollama/blob/main/.github/workflows/go.yml"
    click GOMOD "https://github.com/spoonnotfound/fake-ollama/blob/main/go.mod"
    click GOSUM "https://github.com/spoonnotfound/fake-ollama/blob/main/go.sum"
    click DOCS "https://github.com/spoonnotfound/fake-ollama/blob/main/README.md"
    click LICENSE "https://github.com/spoonnotfound/fake-ollama/tree/main/LICENSE"
    click GITIGNORE "https://github.com/spoonnotfound/fake-ollama/blob/main/.gitignore"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef internal fill:#D0FFD8,stroke:#228B22,color:#228B22;
    classDef config fill:#FFFACD,stroke:#DAA520,color:#DAA520;
    classDef infra fill:#F0F0F0,stroke:#8B8B8B,color:#8B8B8B;
```
