# abuzar-ansarii/privatepixelprompt architecture

> Architecture diagram of the GitHub repository abuzar-ansarii/privatepixelprompt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abuzar-ansarii/privatepixelprompt
- Repository: https://github.com/abuzar-ansarii/privatepixelprompt

## Overview

1. **Overall shape**
   PortableLM is a cross-platform, portable local-AI package. The repository is mostly a set of OS-specific launch/install wrappers around one shared runtime and one shared web UI/server.

2. **Platform boundary**
   The `Windows`, `Linux`, and `Mac` folders contain only thin entrypoint scripts:
   - install/uninstall scripts
   - start scripts
   These are platform adapters; they do not appear to implement the AI logic themselves.

3. **Shared runtime boundary**
   The `Shared` folder is the core of the architecture. It holds the cross-platform assets that are meant to be reused regardless of host OS:
   - `chat_server.py` for the local service
   - `FastChatUI.html` for the browser UI
   - `config/` for model and asset metadata
   - `scripts/` for setup, cleanup, and asset download helpers

4. **Local server + browser UI**
   The main runtime appears to be a Python HTTP server (`Shared/chat_server.py`) that serves the UI and provides the local API for chat/image/TTS actions. The browser is the client, and the server listens locally by default on `localhost:3333`, with LAN access also supported for devices on the same network.

5. **UI delivery**
   `Shared/FastChatUI.html` is the front-end entrypoint. The README indicates the UI is offline-capable and “network proxied,” so the browser page is likely delivered from the local server along with bundled assets rather than pulling from external CDNs.

6. **Model and asset configuration**
   `Shared/config/models.json` is the key metadata boundary for what models are available and how they are presented/selected. `ui-vendor-assets.json` likely maps which vendor UI assets/fonts/scripts must be bundled locally to keep the interface fully offline.

7. **Supporting scripts**
   `Shared/scripts/` contains operational helpers:
   - `download-ui-assets.sh` / `.ps1` for fetching local UI dependencies
   - `config_query.py` for reading/querying configuration state
   - `uninstall-common.sh` for shared cleanup
   This suggests the repo separates one-time provisioning from runtime execution.

8. **Persistent data boundary**
   The README’s folder architecture shows persistent state lives under `Shared` as shared storage, including:
   - chat history
   - generated images
   - TTS outputs
   - downloaded models
   This is the data plane that survives across OSes and across launches.

9. **Engine boundary**
   The README describes packaged local engines for LLMs, image generation, and TTS; these are treated as isolated binaries under the shared storage concept. The repository’s scripts likely install and launch those engines, but the engines themselves are external payloads rather than source code in this tree.

10. **Execution flow**
   Typical flow is:
   - run the OS install script
   - download/extract shared assets, models, and engine binaries
   - launch the OS start script
   - the Python server starts
   - the browser opens to the local UI
   - UI actions are routed to local model engines and results are written back into shared storage

11. **Operational constraints**
   The architecture is explicitly offline-first and air-gapped after setup. There is no cloud service dependency in the repo structure; the main runtime boundary is between local browser clients and the local Python/server-plus-engine stack.

12. **How to diagram it**
   A good architecture diagram should show:
   - three OS-specific launcher boxes feeding into one shared runtime
   - a Python local server in the middle
   - browser clients on localhost and optional LAN devices
   - shared persistence/config/model storage underneath
   - local AI engines as separate binaries behind the server

Main entry points: [`Shared/chat_server.py`](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/chat_server.py) (Server), [`Shared/scripts/download-ui-assets.sh`](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/download-ui-assets.sh) (Asset setup), [`Shared/scripts/uninstall-common.sh`](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/uninstall-common.sh) (Cleanup), [`Windows`](https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Windows) (Windows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platforms["Platform launchers"]
  node_windows_launchers["Windows<br/>launcher bundle"]
  node_linux_launchers["Linux<br/>launcher bundle"]
  node_mac_launchers["Mac<br/>launcher bundle"]
end

subgraph group_runtime["Shared runtime"]
  node_chat_server(("Server<br/>python service<br/>[chat_server.py]"))
  node_fastchat_ui["FastChat UI<br/>browser UI<br/>[FastChatUI.html]"]
  node_models_json["Models<br/>model catalog<br/>[models.json]"]
  node_ui_assets_json["UI assets<br/>asset manifest"]
  node_download_assets["Asset setup<br/>provisioning scripts"]
  node_config_query["Config query<br/>utility script<br/>[config_query.py]"]
  node_cleanup["Cleanup<br/>uninstall script"]
end

subgraph group_clients["Clients"]
  node_local_browser(("Local browser<br/>client"))
  node_lan_clients(("LAN devices<br/>client"))
end

subgraph group_engines["Local engines"]
  node_engines{{"AI engines<br/>local binaries"}}
end

subgraph group_storage["Persistent storage"]
  node_storage[("Shared data<br/>persistent store")]
end

node_windows_launchers -->|"starts"| node_chat_server
node_linux_launchers -->|"starts"| node_chat_server
node_mac_launchers -->|"starts"| node_chat_server
node_chat_server -->|"serves"| node_fastchat_ui
node_fastchat_ui -->|"calls"| node_chat_server
node_local_browser -->|"opens"| node_fastchat_ui
node_lan_clients -->|"reaches"| node_chat_server
node_chat_server -->|"reads"| node_models_json
node_chat_server -->|"reads"| node_ui_assets_json
node_download_assets -->|"uses"| node_ui_assets_json
node_config_query -->|"reads"| node_models_json
node_cleanup -->|"cleans"| node_storage
node_chat_server -->|"writes"| node_storage
node_chat_server -->|"invokes"| node_engines
node_windows_launchers -->|"provisions"| node_download_assets
node_linux_launchers -->|"provisions"| node_download_assets
node_mac_launchers -->|"provisions"| node_download_assets
node_windows_launchers -->|"uninstalls"| node_cleanup
node_linux_launchers -->|"uninstalls"| node_cleanup
node_mac_launchers -->|"uninstalls"| node_cleanup

click node_windows_launchers "https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Windows"
click node_linux_launchers "https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Linux"
click node_mac_launchers "https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Mac"
click node_chat_server "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/chat_server.py"
click node_fastchat_ui "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/FastChatUI.html"
click node_models_json "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/config/models.json"
click node_ui_assets_json "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/config/ui-vendor-assets.json"
click node_download_assets "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/download-ui-assets.sh"
click node_config_query "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/config_query.py"
click node_cleanup "https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/uninstall-common.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_windows_launchers,node_linux_launchers,node_mac_launchers toneBlue
class node_chat_server,node_fastchat_ui,node_models_json,node_ui_assets_json,node_download_assets,node_config_query,node_cleanup toneAmber
class node_local_browser,node_lan_clients toneMint
class node_engines toneRose
class node_storage toneIndigo
```

## Components

### Platform launchers

OS-specific install/start/uninstall wrappers

- [Windows](https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Windows): launcher bundle · Install, start, and uninstall entrypoints for Windows · `Windows`
- [Linux](https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Linux): launcher bundle · Install, start, and uninstall entrypoints for Linux · `Linux`
- [Mac](https://github.com/abuzar-ansarii/privatepixelprompt/tree/main/Mac): launcher bundle · Install, start, and uninstall entrypoints for macOS · `Mac`

### Shared runtime

Cross-platform server, UI, config, and support scripts

- [Server](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/chat_server.py): python service · Local HTTP API and content server for chat, image, and TTS actions · `Shared/chat_server.py`
- [FastChat UI](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/FastChatUI.html): browser UI · Offline-capable front-end served locally · `Shared/FastChatUI.html`
- [Models](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/config/models.json): model catalog · Available model metadata and presentation settings · `Shared/config/models.json`
- [UI assets](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/config/ui-vendor-assets.json): asset manifest · Vendor assets that must be bundled locally for offline UI delivery · `Shared/config/ui-vendor-assets.json`
- [Asset setup](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/download-ui-assets.sh): provisioning scripts · Helpers that fetch UI dependencies and bootstrap local assets · `Shared/scripts/download-ui-assets.sh`
- [Config query](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/config_query.py): utility script · Reads and inspects shared configuration state · `Shared/scripts/config_query.py`
- [Cleanup](https://github.com/abuzar-ansarii/privatepixelprompt/blob/main/Shared/scripts/uninstall-common.sh): uninstall script · Shared removal and cleanup logic · `Shared/scripts/uninstall-common.sh`

### Clients

Local browser access points

- **Local browser**: client · Primary user client loading the UI from localhost
- **LAN devices**: client · Optional devices on the same network reaching the local server

### Local engines

Packaged AI runtimes and model backends

- **AI engines**: local binaries · Packaged LLM, image, and TTS backends launched locally after setup

### Persistent storage

Shared data and downloaded assets that survive launches

- **Shared data**: persistent store · Chat history, generated media, models, and other durable runtime state

## Connections

- Windows → Server: starts · Windows wrappers launch the shared runtime
- Linux → Server: starts · Linux wrappers launch the shared runtime
- Mac → Server: starts · macOS wrappers launch the shared runtime
- Server → FastChat UI: serves · Server delivers the browser UI and local API
- FastChat UI → Server: calls · UI sends chat and generation requests to the local server
- Local browser → FastChat UI: opens · Primary client loads the UI from localhost
- LAN devices → Server: reaches · Optional LAN clients can connect to the local service
- Server → Models: reads · Server uses model metadata to expose choices and capabilities
- Server → UI assets: reads · Server and setup logic rely on the offline asset manifest
- Asset setup → UI assets: uses · Provisioning scripts fetch and bundle declared assets
- Config query → Models: reads · Utility script inspects configuration state
- Cleanup → Shared data: cleans · Shared uninstall path removes persisted artifacts
- Server → Shared data: writes · Chat, image, and TTS outputs are persisted in shared storage
- Server → AI engines: invokes · Runtime dispatches requests to local AI engines
- Windows → Asset setup: provisions · Platform installers trigger shared setup steps
- Linux → Asset setup: provisions · Platform installers trigger shared setup steps
- Mac → Asset setup: provisions · Platform installers trigger shared setup steps
- Windows → Cleanup: uninstalls · Windows uninstall path reuses shared cleanup logic
- Linux → Cleanup: uninstalls · Linux uninstall path reuses shared cleanup logic
- Mac → Cleanup: uninstalls · macOS uninstall path reuses shared cleanup logic