# udayanirogi/promptcapsule architecture

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

- Interactive diagram: https://gitdiagram.com/udayanirogi/promptcapsule
- Repository: https://github.com/udayanirogi/promptcapsule
- Video tour (about a minute): https://gitdiagram.com/udayanirogi/promptcapsule/video

## Overview

PromptCapsule packages prompts as portable inline capsules or vault references, then reconstructs them with integrity checks and optional HMAC verification. The primary workflow is pack, hand off the capsule string, and unpack; long prompts additionally require access to the same vault. The Python convenience API and CLI provide entry points, while the core owns encoding and decoding and invokes the selected storage backend. README capabilities include SQLite, in-memory, GitHub Gist, and S3 backends. Backend and CLI details are based on sampled source; some core implementation sections were omitted.

Main entry points: [`promptcapsule/simple.py`](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/simple.py) (pack / unpack), [`promptcapsule/core.py`](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/core.py) (Vault backend contract), [`promptcapsule/cli.py`](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/cli.py) (CLI commands), [`promptcapsule/backends.py`](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py) (SQLite backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User interfaces"]
  node_simple_api["pack / unpack<br/>[simple.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_capsule["Capsule processing"]
  node_core["Encode / decode<br/>[core.py]"]
  node_integrity["HMAC utilities<br/>[integrity.py]"]
end

subgraph group_vault["Vault storage"]
  node_backend_contract["Vault backend contract<br/>[core.py]"]
  node_memory_backend["In-memory backend<br/>[backends.py]"]
  node_sqlite_backend["SQLite backend<br/>[backends.py]"]
  node_gist_backend["GitHub Gist backend<br/>[backends.py]"]
  node_s3_backend["S3 backend<br/>[backends.py]"]
end

node_caller(("Application or agent"))
node_capsule_string["Capsule string"]
node_sqlite_store[("SQLite vault file")]
node_github["GitHub Gist service"]
node_aws["AWS S3 service"]
node_prompt_text["Prompt text"]

node_caller -->|"calls pack / unpack"| node_simple_api
node_simple_api -->|"compresses / decompresses"| node_core
node_simple_api -->|"resolves vault"| node_backend_contract
node_core -->|"stores / retrieves"| node_backend_contract
node_core -->|"creates signatures"| node_integrity
node_simple_api -->|"returns capsule"| node_capsule_string
node_capsule_string -->|"supplies capsule"| node_simple_api
node_simple_api -->|"returns text"| node_prompt_text
node_prompt_text -->|"supplies text"| node_simple_api
node_caller -->|"runs command"| node_cli
node_cli -->|"packs prompt"| node_simple_api
node_cli -->|"decompresses / verifies"| node_core
node_cli -->|"resolves vault"| node_backend_contract
node_memory_backend -->|"implements"| node_backend_contract
node_sqlite_backend -->|"implements"| node_backend_contract
node_gist_backend -->|"implements"| node_backend_contract
node_s3_backend -->|"implements"| node_backend_contract
node_sqlite_backend -->|"reads / writes"| node_sqlite_store
node_gist_backend -.->|"reads / writes"| node_github
node_s3_backend -.->|"reads / writes"| node_aws

click node_simple_api "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/simple.py"
click node_cli "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/cli.py"
click node_core "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/core.py"
click node_integrity "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/integrity.py"
click node_backend_contract "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/core.py"
click node_memory_backend "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py"
click node_sqlite_backend "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py"
click node_gist_backend "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py"
click node_s3_backend "https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py"

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_simple_api,node_cli toneBlue
class node_core,node_integrity,node_sqlite_store toneAmber
class node_backend_contract,node_memory_backend,node_sqlite_backend,node_gist_backend,node_s3_backend toneMint
class node_caller,node_capsule_string,node_github,node_aws,node_prompt_text toneIndigo
```

## Components

### User interfaces

- [pack / unpack](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/simple.py): `promptcapsule/simple.py`
- [CLI commands](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/cli.py): `promptcapsule/cli.py`

### Capsule processing

- [Encode / decode](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/core.py): `promptcapsule/core.py`
- [HMAC utilities](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/integrity.py): `promptcapsule/integrity.py`

### Vault storage

- [Vault backend contract](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/core.py): `promptcapsule/core.py`
- [In-memory backend](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py): `promptcapsule/backends.py`
- [SQLite backend](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py): `promptcapsule/backends.py`
- [GitHub Gist backend](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py): `promptcapsule/backends.py`
- [S3 backend](https://github.com/udayanirogi/promptcapsule/blob/main/promptcapsule/backends.py): `promptcapsule/backends.py`

### Other components

- **Application or agent**
- **Capsule string**
- **SQLite vault file**
- **GitHub Gist service**
- **AWS S3 service**
- **Prompt text**

## Connections

- Application or agent → pack / unpack: calls pack / unpack
- pack / unpack → Encode / decode: compresses / decompresses
- pack / unpack → Vault backend contract: resolves vault
- Encode / decode → Vault backend contract: stores / retrieves
- Encode / decode → HMAC utilities: creates signatures
- pack / unpack → Capsule string: returns capsule
- Capsule string → pack / unpack: supplies capsule
- pack / unpack → Prompt text: returns text
- Prompt text → pack / unpack: supplies text
- Application or agent → CLI commands: runs command
- CLI commands → pack / unpack: packs prompt
- CLI commands → Encode / decode: decompresses / verifies
- CLI commands → Vault backend contract: resolves vault
- In-memory backend → Vault backend contract: implements
- SQLite backend → Vault backend contract: implements
- GitHub Gist backend → Vault backend contract: implements
- S3 backend → Vault backend contract: implements
- SQLite backend → SQLite vault file: reads / writes
- GitHub Gist backend → GitHub Gist service: reads / writes
- S3 backend → AWS S3 service: reads / writes