# eleshvaishnav/parmana architecture

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

- Interactive diagram: https://gitdiagram.com/eleshvaishnav/parmana
- Repository: https://github.com/eleshvaishnav/parmana

## Overview

1. **Overall shape**
   Parmana is not a client-server app. It is a **local-first AI assistant package** with a small amount of packaging/website infrastructure around it. The core runtime is meant to run on a user’s machine, with no backend API in the steady state.

2. **Primary runtime boundary**
   The main execution path is the **CLI assistant** started via `parmana_bot.py`. That script is the likely entrypoint for interactive chat and for wiring together prompt loading, conversation state, and calls into the local model runtime.

3. **Local model definition**
   `config/Modelfile` is the model/personality boundary. In this repo, it likely defines the assistant’s base behavior and how the underlying local model should be packaged or invoked. This is where the “Parmana” persona is separated from the generic model engine.

4. **System prompt and identity layer**
   `system_prompt.txt` holds the assistant’s core instructions/identity. Architecturally, this is a distinct input to the runtime: it shapes response style, language behavior, and guardrails without embedding that text directly into code.

5. **Memory subsystem**
   `memory/memory.py` is the persistent state layer. It likely manages conversation history or user-specific memory across sessions, which means the assistant has a separate data boundary for state rather than being stateless chat only.

6. **Platform-specific installers**
   `install.sh`, `install.ps1`, `uninstall.sh`, and `uninstall.ps1` form the distribution/bootstrap layer. Their job is to provision the local environment, detect machine capabilities, fetch the right model, and install/remove the `parmana` command. This is the main operational boundary between “repo contents” and “usable app.”

7. **Hardware-aware model selection**
   The README describes RAM-based model selection (0.6B, 2B, 4B, 8B). That implies the installers are responsible for the first major decision in the flow: **choose model size based on available resources**, then download once and run locally thereafter.

8. **Data flow at runtime**
   The intended flow is: user launches `parmana` → `parmana_bot.py` loads `system_prompt.txt` and memory state → local model is invoked using the config-defined model setup → response is returned to the terminal → memory is updated. No external API is part of the normal chat loop.

9. **Persistence and offline behavior**
   The design emphasizes offline use after initial setup. The only expected network dependency is the first-time download of the model and any installation assets. After that, the assistant is supposed to function entirely on-device.

10. **Web/marketing surface**
   `index.html` plus the GitHub Pages workflows under `.github/workflows/` indicate a separate **static site** boundary. This is for project presentation/documentation, not the assistant runtime itself.

11. **Repository operations and CI**
   The GitHub Actions files are for publishing the static site. They are operational infrastructure, not application logic. They support the public-facing landing page and repo maintenance, but they do not participate in conversation processing.

12. **Security and verification artifacts**
   Files like `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue templates, and the Google verification HTML are repository governance/ownership artifacts. They support the project’s public presence but are outside the runtime architecture.

13. **What to draw in an architecture diagram**
   The diagram should center on a **local user machine** containing: the CLI entrypoint, prompt/config files, memory store, and the local model runtime. Surround that with an **install/bootstrap path** that fetches the right model once, plus a separate **static website / GitHub Pages** lane for project distribution.

14. **Key architectural takeaway**
   Parmana’s core architecture is: **static packaging + local model execution + local memory persistence**. There is no central application server; the repository mainly orchestrates how the assistant is installed, personalized, and run on the user’s device.

Main entry points: [`parmana_bot.py`](https://github.com/eleshvaishnav/parmana/blob/main/parmana_bot.py) (CLI bot), [`index.html`](https://github.com/eleshvaishnav/parmana/blob/main/index.html) (Landing page), [`install.sh`](https://github.com/eleshvaishnav/parmana/blob/main/install.sh) (Install script), [`install.ps1`](https://github.com/eleshvaishnav/parmana/blob/main/install.ps1) (PowerShell install)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Local assistant"]
  node_parmana_bot["CLI bot<br/>entrypoint<br/>[parmana_bot.py]"]
  node_system_prompt["System prompt<br/>[system_prompt.txt]"]
  node_model_file["Modelfile<br/>model config"]
  node_memory_store[("Memory<br/>persistent state<br/>[memory.py]")]
  node_local_model{{"Local model<br/>runtime engine"}}
  node_user_terminal["User terminal<br/>user interface"]
end

subgraph group_bootstrap["Installers"]
  node_install_sh["Install script<br/>installer<br/>[install.sh]"]
  node_install_ps1["PowerShell install<br/>installer<br/>[install.ps1]"]
  node_uninstall_sh["Uninstall script<br/>removal<br/>[uninstall.sh]"]
  node_uninstall_ps1["PowerShell uninstall<br/>removal<br/>[uninstall.ps1]"]
  node_readme["README<br/>docs<br/>[README.md]"]
end

subgraph group_web["Site publishing"]
  node_index_html["Landing page<br/>static site<br/>[index.html]"]
  node_gh_pages["Pages workflow<br/>ci publish"]
  node_static_workflow["Static workflow<br/>ci publish<br/>[static.yml]"]
end

subgraph group_gov["Project governance"]
  node_issue_template["Issue template<br/>repo ops<br/>[ISSUE_TEMPLATE.md]"]
  node_bug_template["Bug template<br/>repo ops<br/>[bug_report.md]"]
  node_security["Security<br/>repo policy<br/>[SECURITY.md]"]
  node_conduct["Code of conduct<br/>repo policy<br/>[CODE_OF_CONDUCT.md]"]
  node_contributing["Contributing<br/>repo policy<br/>[CONTRIBUTING.md]"]
  node_verification["Verify HTML<br/>site verification"]
end

node_user_terminal -->|"launches"| node_parmana_bot
node_parmana_bot -->|"loads"| node_system_prompt
node_parmana_bot -->|"reads/writes"| node_memory_store
node_parmana_bot -->|"uses"| node_model_file
node_model_file -->|"configures"| node_local_model
node_parmana_bot -->|"invokes"| node_local_model
node_local_model -->|"returns"| node_parmana_bot
node_install_sh -->|"guided by"| node_readme
node_install_ps1 -->|"guided by"| node_readme
node_install_sh -->|"installs"| node_parmana_bot
node_install_ps1 -->|"installs"| node_parmana_bot
node_install_sh -->|"fetches"| node_local_model
node_install_ps1 -->|"fetches"| node_local_model
node_uninstall_sh -->|"removes"| node_parmana_bot
node_uninstall_ps1 -->|"removes"| node_parmana_bot
node_index_html -->|"published by"| node_gh_pages
node_index_html -->|"published by"| node_static_workflow
node_gh_pages -->|"deploys"| node_index_html
node_static_workflow -->|"deploys"| node_index_html
node_issue_template -->|"uses"| node_bug_template
node_security -->|"supports"| node_contributing
node_conduct -->|"supports"| node_contributing
node_verification -->|"verifies"| node_index_html

click node_parmana_bot "https://github.com/eleshvaishnav/parmana/blob/main/parmana_bot.py"
click node_system_prompt "https://github.com/eleshvaishnav/parmana/blob/main/system_prompt.txt"
click node_model_file "https://github.com/eleshvaishnav/parmana/tree/main/config/Modelfile"
click node_memory_store "https://github.com/eleshvaishnav/parmana/blob/main/memory/memory.py"
click node_install_sh "https://github.com/eleshvaishnav/parmana/blob/main/install.sh"
click node_install_ps1 "https://github.com/eleshvaishnav/parmana/blob/main/install.ps1"
click node_uninstall_sh "https://github.com/eleshvaishnav/parmana/blob/main/uninstall.sh"
click node_uninstall_ps1 "https://github.com/eleshvaishnav/parmana/blob/main/uninstall.ps1"
click node_readme "https://github.com/eleshvaishnav/parmana/blob/main/README.md"
click node_index_html "https://github.com/eleshvaishnav/parmana/blob/main/index.html"
click node_gh_pages "https://github.com/eleshvaishnav/parmana/blob/main/.github/workflows/jekyll-gh-pages.yml"
click node_static_workflow "https://github.com/eleshvaishnav/parmana/blob/main/.github/workflows/static.yml"
click node_issue_template "https://github.com/eleshvaishnav/parmana/blob/main/ISSUE_TEMPLATE.md"
click node_bug_template "https://github.com/eleshvaishnav/parmana/blob/main/.github/ISSUE_TEMPLATE/bug_report.md"
click node_security "https://github.com/eleshvaishnav/parmana/blob/main/SECURITY.md"
click node_conduct "https://github.com/eleshvaishnav/parmana/blob/main/CODE_OF_CONDUCT.md"
click node_contributing "https://github.com/eleshvaishnav/parmana/blob/main/CONTRIBUTING.md"
click node_verification "https://github.com/eleshvaishnav/parmana/blob/main/google21d6399e385c3db7.html"

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_parmana_bot,node_system_prompt,node_model_file,node_memory_store,node_local_model,node_user_terminal toneBlue
class node_install_sh,node_install_ps1,node_uninstall_sh,node_uninstall_ps1,node_readme toneAmber
class node_index_html,node_gh_pages,node_static_workflow toneMint
class node_issue_template,node_bug_template,node_security,node_conduct,node_contributing,node_verification toneRose
```

## Components

### Local assistant

Core on-device chat assistant runtime and its state/prompt inputs.

- [CLI bot](https://github.com/eleshvaishnav/parmana/blob/main/parmana_bot.py): entrypoint · Interactive command-line assistant entrypoint and runtime coordinator. · `parmana_bot.py`
- [System prompt](https://github.com/eleshvaishnav/parmana/blob/main/system_prompt.txt): prompt · Core identity and behavior instructions loaded at runtime. · `system_prompt.txt`
- [Modelfile](https://github.com/eleshvaishnav/parmana/tree/main/config/Modelfile): model config · Local model/persona packaging and invocation definition. · `config/Modelfile`
- [Memory](https://github.com/eleshvaishnav/parmana/blob/main/memory/memory.py): persistent state · Conversation or user state persisted across sessions. · `memory/memory.py`
- **Local model**: runtime engine · On-device model runtime used to generate responses.
- **User terminal**: user interface · Where the user launches the assistant and reads responses.

### Installers

Platform-specific setup and removal path for the local command and model.

- [Install script](https://github.com/eleshvaishnav/parmana/blob/main/install.sh): installer · Unix bootstrap script for provisioning the assistant and model. · `install.sh`
- [PowerShell install](https://github.com/eleshvaishnav/parmana/blob/main/install.ps1): installer · Windows bootstrap script for provisioning the assistant and model. · `install.ps1`
- [Uninstall script](https://github.com/eleshvaishnav/parmana/blob/main/uninstall.sh): removal · Unix removal script for uninstalling the assistant setup. · `uninstall.sh`
- [PowerShell uninstall](https://github.com/eleshvaishnav/parmana/blob/main/uninstall.ps1): removal · Windows removal script for uninstalling the assistant setup. · `uninstall.ps1`
- [README](https://github.com/eleshvaishnav/parmana/blob/main/README.md): docs · Primary setup and model-selection guidance for users and installers. · `README.md`

### Site publishing

Static site and GitHub Pages automation for project presentation.

- [Landing page](https://github.com/eleshvaishnav/parmana/blob/main/index.html): static site · Public project website and marketing surface. · `index.html`
- [Pages workflow](https://github.com/eleshvaishnav/parmana/blob/main/.github/workflows/jekyll-gh-pages.yml): ci publish · GitHub Actions workflow for publishing the static site. · `.github/workflows/jekyll-gh-pages.yml`
- [Static workflow](https://github.com/eleshvaishnav/parmana/blob/main/.github/workflows/static.yml): ci publish · GitHub Actions workflow supporting static site publication. · `.github/workflows/static.yml`

### Project governance

Repository policy and contribution/verification artifacts.

- [Issue template](https://github.com/eleshvaishnav/parmana/blob/main/ISSUE_TEMPLATE.md): repo ops · Repository template for issue reporting and community workflow. · `ISSUE_TEMPLATE.md`
- [Bug template](https://github.com/eleshvaishnav/parmana/blob/main/.github/ISSUE_TEMPLATE/bug_report.md): repo ops · Structured bug report template for contributors. · `.github/ISSUE_TEMPLATE/bug_report.md`
- [Security](https://github.com/eleshvaishnav/parmana/blob/main/SECURITY.md): repo policy · Security policy and reporting guidance. · `SECURITY.md`
- [Code of conduct](https://github.com/eleshvaishnav/parmana/blob/main/CODE_OF_CONDUCT.md): repo policy · Community behavior and contribution standards. · `CODE_OF_CONDUCT.md`
- [Contributing](https://github.com/eleshvaishnav/parmana/blob/main/CONTRIBUTING.md): repo policy · Contribution guidelines for the project. · `CONTRIBUTING.md`
- [Verify HTML](https://github.com/eleshvaishnav/parmana/blob/main/google21d6399e385c3db7.html): site verification · Ownership verification artifact for search or hosting services. · `google21d6399e385c3db7.html`

## Connections

- User terminal → CLI bot: launches · User starts the assistant from the terminal.
- CLI bot → System prompt: loads · Runtime reads the assistant identity and guardrails.
- CLI bot → Memory: reads/writes · Conversation state is persisted between sessions.
- CLI bot → Modelfile: uses · CLI runtime uses the local model packaging definition.
- Modelfile → Local model: configures · Model file defines how the local model is packaged or invoked.
- CLI bot → Local model: invokes · Interactive requests are sent to the local model runtime.
- Local model → CLI bot: returns · Generated responses flow back to the CLI assistant.
- Install script → README: guided by · Unix installation follows the documented setup and model choice.
- PowerShell install → README: guided by · Windows installation follows the documented setup and model choice.
- Install script → CLI bot: installs · Bootstrap path installs the assistant command on Unix.
- PowerShell install → CLI bot: installs · Bootstrap path installs the assistant command on Windows.
- Install script → Local model: fetches · Installer downloads the selected local model during first setup.
- PowerShell install → Local model: fetches · Installer downloads the selected local model during first setup.
- Uninstall script → CLI bot: removes · Unix uninstall path removes the installed assistant command.
- PowerShell uninstall → CLI bot: removes · Windows uninstall path removes the installed assistant command.
- Landing page → Pages workflow: published by · Landing page is deployed through the Pages workflow.
- Landing page → Static workflow: published by · Static site publication is handled by repository automation.
- Pages workflow → Landing page: deploys · Workflow publishes the static landing page.
- Static workflow → Landing page: deploys · Workflow publishes the static landing page.
- Issue template → Bug template: uses · General issue reporting is complemented by a bug-specific template.
- Security → Contributing: supports · Governance documents define project participation boundaries.
- Code of conduct → Contributing: supports · Community standards complement contribution guidance.
- Verify HTML → Landing page: verifies · Ownership verification artifact supports the public site.
