# dkruyt/webollama architecture

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

- Interactive diagram: https://gitdiagram.com/dkruyt/webollama
- Repository: https://github.com/dkruyt/webollama

## Overview

##### Project type and purpose
- This is a full-stack web application (“WebOllama”) built with Python Flask on the backend and Bootstrap on the frontend.
- Purpose: Provide a browser-based interface for managing local Ollama LLM models, chatting/generating text, and viewing version updates.

##### File structure
- Top-level files:
- app.py – single monolithic Flask application entrypoint with all HTTP routes/controllers
- Dockerfile, docker-compose.yml & docker-compose.ollama.yml – containerization and multi-service orchestration
- setup.sh, requirements.txt – bootstrap script and Python dependencies
- .github/workflows/docker-build.yml – CI pipeline for building the Docker image
- Directories:
- templates/ – HTML view templates (MVC view)
- static/css/ – CSS assets (MVC static assets)
- assets/ – project screenshots and images used in README (documentation assets)
- No database folder: state is ephemeral/in-memory or managed by external Ollama server.

##### README for technical stack and architecture hints
- Flask for the web server
- Bootstrap for responsive UI
- Ollama API service running locally (default on http://127.0.0.1:11434) as an external microservice
- Optional use of GitHub Releases API to fetch changelogs
- Two “deploy” modes via Docker Compose:
1. WebOllama container only (connects to host’s Ollama)
2. Both Ollama and WebOllama containers in the same network

##### Key components
a. Client Browser (Chrome/Firefox on desktop or mobile) – sends HTTP(S) requests
b. WebOllama Flask App
- Routes/Controllers (in app.py)
- Template Rendering (templates/)
- Static Asset Server (static/, CSS/JS)
- Session Management (Flask sessions with SECRET_KEY)
- External API adapters:
- Ollama API for model management & inference
- GitHub Releases API for version/changelog
c. Ollama API Service (local LLM server, default port 11434)
d. Docker Infrastructure (optional view)
- webollama container
- ollama container
- Docker bridge network
- GitHub Actions workflow that builds and publishes Docker images

##### Relationships & data flow
- Browser → (HTTP) → Flask App
- Flask App → (HTTP REST) → Ollama API Service (model pulls, inference, stats)
- Flask App → (HTTPS REST) → GitHub Releases (fetch changelog)
- Flask App → Template Engine → Served HTML/CSS/JS → Browser
- Optional: Docker Compose network connecting webollama and ollama containers
- CI pipeline pushes new Docker images to registry, which Docker Compose pulls

##### Architectural patterns & design principles
- MVC (Model: external Ollama, View: Jinja2 templates, Controller: Flask routes)
- Adapter pattern for abstracting the external Ollama & GitHub APIs behind Python functions
- Containerization & microservices: separate container for Ollama LLM, isolated network
- Single-page-style interactions via dynamic endpoints (chat streaming, JSON fetches)

##### Essential details without over-splitting
- Integration points: where data flows in/out of your app
- Optional and alternate paths: two Docker-Compose flavors, direct host-based Ollama vs. containerized Ollama

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Tier
    subgraph "Presentation Tier"
        direction TB
        Browser["Client Browser"]:::presentation
        Static["Static Assets (CSS/JS)"]:::presentation
        Templates["Jinja2 Templates"]:::presentation
    end

    %% Application Tier
    subgraph "Application Tier"
        direction TB
        FlaskApp["Flask App (app.py)"]:::application
        Session["Session Management (.env)"]:::application
        Requirements["Dependencies (requirements.txt)"]:::application
        SetupScript["Setup Script"]:::application
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OllamaAPI["Ollama API Service<br/>(11434/tcp)"]:::external
        GitHubAPI["GitHub Releases API"]:::external
    end

    %% Docker Infrastructure
    subgraph "Docker Network"    
        direction TB
        WebContainer["WebOllama Container"]:::infra
        OllamaContainer["Ollama Container"]:::infra
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI["GitHub Actions Pipeline"]:::infra
    end

    %% Documentation & Assets
    subgraph "Documentation"
        direction TB
        README["README.md"]:::docs
        Assets["assets/"]:::docs
    end

    %% Connections
    Browser -->|HTTP Requests| FlaskApp
    FlaskApp -->|Serves HTML/CSS/JS| Browser
    FlaskApp -->|Serves Static Files| Static
    FlaskApp -->|Renders Templates| Templates
    FlaskApp -->|Uses Config| Session
    FlaskApp -->|Installs Dependencies| Requirements
    FlaskApp -->|Bootstrap Setup| SetupScript
    FlaskApp -->|"GET /models<br/>POST /chat"| OllamaAPI
    FlaskApp -->|"GET /changelog"| GitHubAPI

    WebContainer -->|Internal HTTP| OllamaContainer
    CI -->|Builds & Publishes Images| WebContainer
    CI -->|Builds & Publishes Images| OllamaContainer

    README -->|Docs & Architecture| Browser
    Assets -->|Documentation| README

    %% Click Events
    click FlaskApp "https://github.com/dkruyt/webollama/blob/main/app.py"
    click Templates "https://github.com/dkruyt/webollama/tree/main/templates/"
    click Static "https://github.com/dkruyt/webollama/tree/main/static/"
    click Session "https://github.com/dkruyt/webollama/blob/main/.env.example"
    click Requirements "https://github.com/dkruyt/webollama/blob/main/requirements.txt"
    click SetupScript "https://github.com/dkruyt/webollama/blob/main/setup.sh"
    click README "https://github.com/dkruyt/webollama/blob/main/README.md"
    click Assets "https://github.com/dkruyt/webollama/tree/main/assets/"
    click CI "https://github.com/dkruyt/webollama/blob/main/.github/workflows/docker-build.yml"
    click WebContainer "https://github.com/dkruyt/webollama/blob/main/docker-compose.yml"
    click OllamaContainer "https://github.com/dkruyt/webollama/blob/main/docker-compose.ollama.yml"
    click CI "https://github.com/dkruyt/webollama/tree/main/Dockerfile"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,color:#004085;
    classDef application fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef infra fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef docs fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
