# gowthamganesanamibikapthy/supreme-garbanzo architecture

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

- Interactive diagram: https://gitdiagram.com/gowthamganesanamibikapthy/supreme-garbanzo
- Repository: https://github.com/gowthamganesanamibikapthy/supreme-garbanzo

## Overview

#### Purpose and Entry Points
This repository appears to implement an “Aura” desktop-oriented application with local backend services, task/auth/data handling, a GUI client, and a separate marketplace-facing JavaScript surface. Primary launch and audit entry points are `run_aura.bat` and `run_sit_audit.py`.

#### Desktop Application Shell
The desktop frontend is the likely user-facing control plane. `desktop_frontend/main_client.py` likely composes application startup and backend interaction; `desktop_frontend/dashboard_hud.py` provides the primary dashboard view; `desktop_frontend/system_tray.py` manages background/tray lifecycle. The frontend boundary is local UI code versus service calls into `core_backend/`.

#### Visual Rendering Layer
`desktop_frontend/paint_engine.py` is a distinct rendering/painting subsystem, separated from dashboard orchestration. This suggests display composition or custom visual effects should remain isolated from business logic and service communication.

#### Backend Service Boundary
`core_backend/app_service.py` is the probable application-level coordinator for desktop requests. It should own cross-service workflows rather than placing them in UI code. `core_backend/auth_service.py` encapsulates identity/session concerns, while `core_backend/task_service.py` owns task lifecycle and task-oriented operations.

#### Persistence
`core_backend/database.py` centralizes database access and is the persistence boundary for backend services. `aura_sit_test_sandbox.db` is a repository-local database artifact, likely used for sandbox or system-integration testing data. Callers should reach persistence through backend services rather than directly coupling UI modules to the database.

#### Primary Flow
The expected control flow is:
1. `run_aura.bat` starts the Aura application.
2. `desktop_frontend/main_client.py` initializes desktop UI components.
3. Dashboard/tray interactions route through `core_backend/app_service.py`.
4. The app service delegates authentication and task work to `core_backend/auth_service.py` and `core_backend/task_service.py`.
5. Backend services use `core_backend/database.py` to read/write persisted state.

#### External-Facing Marketplace Surface
`web_storefront/marketplace.js` is a separate JavaScript marketplace/storefront integration boundary. It should be treated as independent from the desktop runtime unless explicitly connected through a shared API or data contract. No server framework, cloud provider, or external SaaS dependency is identifiable from the supplied tree.

#### Verification Boundary
`run_sit_audit.py` is a system-integration-test or audit entry point. It likely validates the assembled backend/database behavior using the sandbox data path rather than serving as a production runtime component.

Main entry points: [`core_backend/app_service.py`](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/app_service.py) (App service), [`desktop_frontend/main_client.py`](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/main_client.py) (Main client), [`desktop_frontend/dashboard_hud.py`](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/dashboard_hud.py) (Dashboard HUD), [`run_sit_audit.py`](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/run_sit_audit.py) (SIT audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Runtime"]
  node_launcher["Aura launcher<br/>batch entry point<br/>[run_aura.bat]"]
  node_main_client["Main client<br/>desktop client<br/>[main_client.py]"]
  node_dashboard["Dashboard HUD<br/>desktop view<br/>[dashboard_hud.py]"]
  node_tray["System tray<br/>lifecycle UI<br/>[system_tray.py]"]
  node_paint_engine["Paint engine<br/>rendering subsystem<br/>[paint_engine.py]"]
end

subgraph group_backend["Core Backend"]
  node_app_service{{"App service<br/>application coordinator<br/>[app_service.py]"}}
  node_auth_service["Auth service<br/>identity service<br/>[auth_service.py]"]
  node_task_service["Task service<br/>[task_service.py]"]
  node_database[("Database access<br/>persistence boundary<br/>[database.py]")]
end

subgraph group_verification["Verification"]
  node_sandbox_db[("SIT sandbox database<br/>SQLite database")]
  node_sit_audit["SIT audit<br/>audit entry point<br/>[run_sit_audit.py]"]
end

node_marketplace["Marketplace storefront<br/>JavaScript integration<br/>[marketplace.js]"]

node_launcher -->|"starts"| node_main_client
node_main_client -->|"initializes"| node_dashboard
node_main_client -->|"initializes"| node_tray
node_dashboard -->|"renders through"| node_paint_engine
node_main_client -->|"requests workflows"| node_app_service
node_dashboard -->|"user actions"| node_app_service
node_tray -->|"background actions"| node_app_service
node_app_service -->|"delegates authentication"| node_auth_service
node_app_service -->|"delegates task work"| node_task_service
node_auth_service -->|"reads and writes state"| node_database
node_task_service -->|"reads and writes tasks"| node_database
node_sit_audit -.->|"audits assembled behavior"| node_app_service
node_sit_audit -->|"uses sandbox data"| node_sandbox_db

click node_launcher "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/run_aura.bat"
click node_main_client "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/main_client.py"
click node_dashboard "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/dashboard_hud.py"
click node_tray "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/system_tray.py"
click node_paint_engine "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/paint_engine.py"
click node_app_service "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/app_service.py"
click node_auth_service "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/auth_service.py"
click node_task_service "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/task_service.py"
click node_database "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/database.py"
click node_sandbox_db "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/aura_sit_test_sandbox.db"
click node_sit_audit "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/run_sit_audit.py"
click node_marketplace "https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/web_storefront/marketplace.js"

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_launcher,node_main_client,node_dashboard,node_tray,node_paint_engine toneBlue
class node_app_service,node_auth_service,node_task_service,node_database toneAmber
class node_sandbox_db,node_sit_audit toneMint
class node_marketplace toneNeutral
```

## Components

### Desktop Runtime

- [Aura launcher](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/run_aura.bat): batch entry point · Starts the Aura desktop application. · `run_aura.bat`
- [Main client](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/main_client.py): desktop client · Composes startup and backend interaction. · `desktop_frontend/main_client.py`
- [Dashboard HUD](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/dashboard_hud.py): desktop view · Primary dashboard interface. · `desktop_frontend/dashboard_hud.py`
- [System tray](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/system_tray.py): lifecycle UI · Manages background and tray lifecycle. · `desktop_frontend/system_tray.py`
- [Paint engine](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/desktop_frontend/paint_engine.py): rendering subsystem · Keeps visual composition separate from business logic. · `desktop_frontend/paint_engine.py`

### Core Backend

- [App service](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/app_service.py): application coordinator · Coordinates workflows requested by the desktop client. · `core_backend/app_service.py`
- [Auth service](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/auth_service.py): identity service · Encapsulates identity and session concerns. · `core_backend/auth_service.py`
- [Task service](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/task_service.py): task service · Owns task lifecycle operations. · `core_backend/task_service.py`
- [Database access](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/core_backend/database.py): persistence boundary · Centralizes backend database access. · `core_backend/database.py`

### Verification

- [SIT sandbox database](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/aura_sit_test_sandbox.db): SQLite database · Repository-local sandbox or integration-test data. · `aura_sit_test_sandbox.db`
- [SIT audit](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/run_sit_audit.py): audit entry point · Validates assembled backend and database behavior. · `run_sit_audit.py`

### Other components

- [Marketplace storefront](https://github.com/gowthamganesanamibikapthy/supreme-garbanzo/blob/main/web_storefront/marketplace.js): JavaScript integration · Independent marketplace-facing surface. · `web_storefront/marketplace.js`

## Connections

- Aura launcher → Main client: starts
- Main client → Dashboard HUD: initializes
- Main client → System tray: initializes
- Dashboard HUD → Paint engine: renders through
- Main client → App service: requests workflows
- Dashboard HUD → App service: user actions
- System tray → App service: background actions
- App service → Auth service: delegates authentication
- App service → Task service: delegates task work
- Auth service → Database access: reads and writes state
- Task service → Database access: reads and writes tasks
- SIT audit → App service: audits assembled behavior
- SIT audit → SIT sandbox database: uses sandbox data