# garricklin/lite_proxy architecture

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

- Interactive diagram: https://gitdiagram.com/garricklin/lite_proxy
- Repository: https://github.com/garricklin/lite_proxy

## Overview

##### Project Type and Purpose
- This is a lightweight proxy service that is fully OpenAI API compatible. It is designed to act as an API gateway with multi-backend configuration capabilities.
- It supports key features such as request forwarding, streaming response support, detailed logging, and a management interface. It uses FastAPI for the API service and Streamlit for the admin GUI. MongoDB is used for persistent data storage.

##### Analyzing the File Structure
- The project is organized into three main directories:
- admin: Contains the management GUI (with its main entry point “gui.py” and separate pages for async conversation, configuration management, and log viewing).
- core: Holds core components, such as configuration management (config.py) and database connectivity (database.py).
- proxy: Contains the proxy service components including API routes (api_routes.py), proxy logic (proxy_logic.py), and data models (models.py).
- The top-level “main.py” acts as the primary entry point for running the proxy service.
- Additional configuration files (Dockerfile, docker-compose.yml, .env.example, requirements.txt) indicate deployment support and containerization with Docker and Docker Compose.

##### Project Architecture Insights from the README
- The README explains two different modes for running the service: directly via Uvicorn (for the API) and Streamlit (for the admin GUI) or through Docker Compose.
- Docker Compose launches three distinct services:
▪ proxy-api: The main API service (using FastAPI).
▪ proxy-admin: The admin interface (running on Streamlit).
▪ proxy-db: The MongoDB database.
- The README highlights critical technologies: FastAPI, Streamlit, MongoDB with an async driver (Motor), and HTTPX for asynchronous HTTP requests.

##### Main Components
a. API Proxy Service:
- Represented by “main.py” invoking components in the “proxy/” directory.
- Contains a service layer that handles incoming API requests (via routes in “proxy/api_routes.py”), processes those using “proxy/proxy_logic.py”, and communicates with backend services.
b. Management Interface:
- Represented by the “admin/” directory with “gui.py” as the main entry point.
- Includes individual page modules (async_conversation.py, config_management.py, and log_viewer.py) for testing API features, managing configurations, and viewing logs.
c. Core Components:
- Under the “core/” directory, these modules manage central configurations (config.py) and database interactions (database.py).
d. Database:
- MongoDB, as indicated by both the README and configuration examples.
e. Docker/Deployment:
- Dockerfile and docker-compose.yml indicate containerized deployment with distinct containers for the API proxy, admin interface, and MongoDB database.

##### Relationships and Interactions
- The API Proxy Service (FastAPI) receives incoming requests and, through the proxy logic, routes them to the appropriate backends as configured.
- The Core components support this by providing configuration data and establishing connections with the database.
- The Management Interface sits as an independent client service that connects to the database and, possibly, to the API service for administrative or testing actions (e.g., asynchronous conversation tests).
- The Docker Compose configuration ties these services together by mapping ports and service dependencies.

##### Architectural Patterns/Design Principles & Technologies
- Separation of concerns is maintained by splitting administrative functions (Streamlit-based GUI) from core proxy functions (FastAPI).
- The use of asynchronous programming is evident (via Motor and HTTPX) for handling API requests and responses (including streaming).
- The containerized deployment model (Docker, Docker Compose) clarifies isolation of services.
- Each module is clearly divided by its responsibility (routing, logic, database configuration, UI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Side"
        user["User"]:::client
    end

    %% API Proxy Service Layer
    subgraph "API Proxy Service (FastAPI)"
        main["main.py"]:::backend
        routes["api_routes.py"]:::backend
        proxyLogic["proxy_logic.py"]:::backend
        models["models.py"]:::backend
    end

    %% Core Components Layer
    subgraph "Core Components"
        config["config.py"]:::backend
        databaseComp["database.py"]:::backend
    end

    %% Management Interface Layer
    subgraph "Management Interface (Streamlit)"
        gui["gui.py"]:::admin
        asyncPage["async_conversation.py"]:::admin
        configMgmt["config_management.py"]:::admin
        logViewer["log_viewer.py"]:::admin
    end

    %% Deployment Layer
    subgraph "Deployment/Containerization"
        dockerfile["Dockerfile"]:::docker
        compose["docker-compose.yml"]:::docker
        envFile[".env.example"]:::docker
    end

    %% Container Layer
    subgraph "Docker Containers"
        containerAPI["proxy-api (FastAPI)"]:::docker
        containerAdmin["proxy-admin (Streamlit)"]:::docker
        containerDB["proxy-db (MongoDB)"]:::docker
    end

    %% Database Layer
    subgraph "Database"
        mongo["MongoDB"]:::database
    end

    %% Relationships
    user -->|"uses API"| main
    user -->|"accesses Admin"| gui

    main -->|"calls"| routes
    routes -->|"invokes"| proxyLogic
    proxyLogic -->|"utilizes"| models
    proxyLogic -->|"fetchesConfig"| config
    proxyLogic -->|"logsTo"| databaseComp
    config -->|"connectsTo"| databaseComp
    databaseComp -->|"linksTo"| mongo

    gui -->|"executes"| asyncPage
    gui -->|"manages"| configMgmt
    gui -->|"views"| logViewer
    gui -->|"queries"| mongo

    %% Deployment connections
    compose --> containerAPI
    compose --> containerAdmin
    compose --> containerDB
    containerAPI -->|"runs"| main
    containerAPI -->|"hosts"| routes
    containerAPI -->|"operates"| proxyLogic
    containerAPI -->|"includes"| models
    containerAdmin -->|"runs"| gui
    containerDB -->|"provides"| mongo

    %% Click Events for API Proxy Service
    click main "https://github.com/garricklin/lite_proxy/blob/main/main.py"
    click routes "https://github.com/garricklin/lite_proxy/blob/main/proxy/api_routes.py"
    click proxyLogic "https://github.com/garricklin/lite_proxy/blob/main/proxy/proxy_logic.py"
    click models "https://github.com/garricklin/lite_proxy/blob/main/proxy/models.py"

    %% Click Events for Management Interface
    click gui "https://github.com/garricklin/lite_proxy/blob/main/admin/gui.py"
    click asyncPage "https://github.com/garricklin/lite_proxy/blob/main/admin/pages/async_conversation.py"
    click configMgmt "https://github.com/garricklin/lite_proxy/blob/main/admin/pages/config_management.py"
    click logViewer "https://github.com/garricklin/lite_proxy/blob/main/admin/pages/log_viewer.py"

    %% Click Events for Core Components
    click config "https://github.com/garricklin/lite_proxy/blob/main/core/config.py"
    click databaseComp "https://github.com/garricklin/lite_proxy/blob/main/core/database.py"

    %% Click Events for Deployment/Containerization
    click dockerfile "https://github.com/garricklin/lite_proxy/tree/main/Dockerfile"
    click compose "https://github.com/garricklin/lite_proxy/blob/main/docker-compose.yml"
    click envFile "https://github.com/garricklin/lite_proxy/blob/main/.env.example"

    %% Styles
    classDef backend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef admin fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef database fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef docker fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef client fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
