# adhilgafoor00-stack/spektra architecture

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

- Interactive diagram: https://gitdiagram.com/adhilgafoor00-stack/spektra
- Repository: https://github.com/adhilgafoor00-stack/spektra

## Overview

This is a **single-process Flask web application** that serves a **local, modular “intelligent assistant”**. It provides:
- A **web UI** (HTML/CSS/JS) with “HUD widgets” (clock/system/network stats).
- An **assistant core** that parses commands and routes them to “tools” / “skills”.
- **Memory + learning** persisted to JSON (`data/memory.json`, `data/facts.json`).
- Optional **external integrations** (Wikipedia, DuckDuckGo) depending on installed packages / network availability.
- A **project generator** tool (`genproj`) and small utilities (file manager, calculator, code snippets).

##### Entry point / Web server
- `app.py`
Likely creates the Flask app, defines HTTP routes, serves `templates/index.html`, and exposes endpoints used by `static/js/app.js` for:
- sending user commands
- fetching widget data

##### Core assistant engine (domain layer)
- `core/assistant.py`
**Central orchestrator**: command parsing, dispatch, response formatting.
- `core/tools.py`
“Tool registry” / execution layer (calc/search/code/genproj/etc).
- `core/memory.py`
Persistence + retrieval for notes/recall; reads/writes `data/memory.json`.
- `core/learn.py`
“teach/facts/ask retrieval” logic; reads/writes `data/facts.json`; used by assistant for Q&A.
- `core/widgets.py`
Provides widget data (clock/system/network) to UI; depends on `psutil` optionally.

##### Extensible skills (plugin-like layer)
- `skills/` (`skills/general.py`, `skills/file_manager.py`, `skills/__init__.py`)

##### Data stores (local persistence)
- `data/facts.json`
- `data/memory.json`

##### Build/runtime config
- `requirements.txt`
Shows runtime dependencies (not architecture per se, but important callouts: `Flask`, `wikipedia`, `psutil`).

##### Browser UI (`index.html` + `app.js`)
→ sends user text command over HTTP (likely AJAX/fetch)
##### Flask app (`app.py`)
→ calls **Assistant** (`core/assistant.py`)
##### Assistant
→ routes to:
- **Tools layer** (`core/tools.py`) and/or **Skills** (`skills/*`)
- **Memory** (`core/memory.py`) for `save/recall/notes`
- **Learning** (`core/learn.py`) for `teach/facts/ask` (local facts retrieval)
##### Optional external calls
- `ask` may call **Wikipedia API** (via `wikipedia` package)
- `search` may call **DuckDuckGo** (or open a URL / scrape depending on implementation)
##### Assistant returns response
→ **Flask** returns JSON/HTML
→ **Browser** renders output

##### Persistence flows
- `teach ...` → `core/learn.py` → writes `data/facts.json`
- `save note ...` → `core/memory.py` → writes `data/memory.json`
- `facts/recall` → read from those JSON files

##### Project generation / filesystem operations (security-relevant)
- `genproj ...` and `ls/cat` → skills/tools that **read/write local filesystem**

##### Architectural pattern callouts (what to label explicitly)
- **Modular Monolith**: one Flask process, separated into core modules + skills.
- **Command Router / Dispatcher**: assistant parses text → routes to a handler (tools/skills).
- **Plugin-like Skills**: `skills/` directory as extensibility point (add new capabilities without rewriting core).
- **File-based persistence**: JSON “datastores” instead of DB.
- **Graceful degradation**: widgets degrade if `psutil` missing; `ask` falls back if Wikipedia missing.

Use this as the exact layout:

- User
→ Browser (templates/index.html + static/js/app.js + static/css/styles.css)
⇄ HTTP/JSON
Flask App (app.py)
→ core/assistant.py (parse + dispatch)
→ core/tools.py (tool execution)
→ skills/general.py
→ skills/file_manager.py (filesystem ops)
→ (search / code / genproj handlers)
→ core/memory.py ⇄ data/memory.json
→ core/learn.py ⇄ data/facts.json
→ (ask) ⇄ Wikipedia (optional)
→ (search) ⇄ DuckDuckGo (optional)
→ core/widgets.py → psutil/OS (optional) → returns widget JSON

## Diagram (Mermaid)

```mermaid
flowchart TD
    %%========================
    %% Diagram 1 — System Context / Container
    %%========================
    subgraph "Diagram 1 — System Context (Modular Monolith; Local-first)"
        direction TB

        U["User"]:::external

        subgraph "Browser Sandbox Boundary"
            direction TB
            B["Browser (Web UI)"]:::frontend
            UIHTML["templates/index.html"]:::frontend
            UIJS["static/js/app.js"]:::frontend
            UICSS["static/css/styles.css"]:::frontend
            B -->|"renders"| UIHTML
            B -->|"loads"| UIJS
            B -->|"loads"| UICSS
        end

        subgraph "Flask Process Boundary (Single Python process)"
            direction TB
            F["Flask App (app.py)"]:::backend
            A["Assistant Core (core/assistant.py)"]:::backend
        end

        subgraph "Local Disk Boundary"
            direction TB
            DJSON[("JSON files on local disk\n(data/memory.json, data/facts.json)")]:::datastore
            DFS[("OS Filesystem\n(projects/files)")]:::datastore
        end

        subgraph "External Internet Boundary (Optional)"
            direction TB
            WIKI["Wikipedia API (optional)"]:::external
            DDG["DuckDuckGo (optional)"]:::external
        end

        U -->|"types command / views HUD"| B
        B <-->|"HTTP (JSON)"| F
        F -->|"calls"| A

        F <-->|"Read/Write JSON"| DJSON
        F <-->|"Filesystem R/W"| DFS

        F -.->|"HTTPS (optional)"| WIKI
        F -.->|"HTTPS (optional)"| DDG

        NOTE1["Patterns:\n- Modular Monolith\n- Command Router/Dispatcher\n- Plugin-like Skills\n- File-based persistence\n- Graceful degradation (psutil/wikipedia optional)"]:::note
        A --- NOTE1
    end

    %%========================
    %% Diagram 2 — Component Diagram (Inside Flask app)
    %%========================
    subgraph "Diagram 2 — Component Diagram (Inside Flask App)"
        direction TB

        subgraph "Presentation Layer"
            direction TB
            C_B["Browser UI"]:::frontend
            C_HTML["templates/index.html"]:::frontend
            C_JS["static/js/app.js"]:::frontend
            C_CSS["static/css/styles.css"]:::frontend
            C_B -->|"renders"| C_HTML
            C_B -->|"executes"| C_JS
            C_B -->|"applies"| C_CSS
        end

        subgraph "Application Layer (Routes/Controllers)"
            direction TB
            R["Flask Routes (app.py)"]:::backend
        end

        subgraph "Domain Layer (Assistant Core)"
            direction TB
            ASST["Assistant Orchestrator / Command Router (core/assistant.py)"]:::backend
            TOOLS["Tools Registry / Executor (core/tools.py)"]:::backend

            subgraph "Skills (Pluggable) — skills/"
                direction TB
                SK_INIT["skills/__init__.py"]:::backend
                SK_GEN["General Skills (skills/general.py)"]:::backend
                SK_FM["File Manager Skill (skills/file_manager.py)"]:::backend
            end

            MEM["Memory Store (core/memory.py)"]:::backend
            LEARN["Learning / Facts Store (core/learn.py)"]:::backend
            WDG["Widgets Provider (core/widgets.py)"]:::backend
        end

        subgraph "Persistence & System Resources"
            direction TB
            MEMJSON[("data/memory.json")]:::datastore
            FACTSJSON[("data/facts.json")]:::datastore
            OSFS[("OS Filesystem\n(genproj, ls/cat R/W)")]:::datastore
            PSUTIL["psutil / OS stats (optional)"]:::external
        end

        subgraph "External Integrations (Optional)"
            direction TB
            EXT_WIKI["Wikipedia API (optional)"]:::external
            EXT_DDG["DuckDuckGo (optional)"]:::external
        end

        REQ["requirements.txt (deps: Flask, wikipedia, psutil, etc.)"]:::config

        %% Primary: command execution flow
        C_B <-->|"HTTP (JSON)\ncommands/responses"| R
        R -->|"dispatches command"| ASST
        ASST -->|"routes to tools/skills"| TOOLS
        TOOLS -->|"invokes"| SK_GEN
        TOOLS -->|"invokes"| SK_FM

        %% Persistence flows
        ASST -->|"save/recall notes"| MEM
        MEM <-->|"Read/Write JSON"| MEMJSON

        ASST -->|"teach/ask facts"| LEARN
        LEARN <-->|"Read/Write JSON"| FACTSJSON

        %% Optional external calls
        ASST -.->|"ask -> HTTPS (optional)"| EXT_WIKI
        ASST -.->|"search -> HTTPS (optional)"| EXT_DDG

        %% Widget refresh flow
        C_JS -->|"poll widgets (HTTP JSON)"| R
        R -->|"widget endpoint"| WDG
        WDG -.->|"reads stats (optional)"| PSUTIL

        %% Filesystem ops boundary
        SK_FM -->|"Filesystem R/W"| OSFS
        TOOLS -->|"genproj / file ops"| OSFS

        %% Config note
        R --- REQ

        NOTE2["Trust boundaries:\n- Browser sandbox\n- Flask process\n- Local disk\n- External internet"]:::note
        R --- NOTE2
    end

    %%========================
    %% Click Events (from component_mapping)
    %%========================
    click F "https://github.com/adhilgafoor00-stack/spektra/blob/main/app.py"
    click R "https://github.com/adhilgafoor00-stack/spektra/blob/main/app.py"

    click A "https://github.com/adhilgafoor00-stack/spektra/blob/main/core/assistant.py"
    click ASST "https://github.com/adhilgafoor00-stack/spektra/blob/main/core/assistant.py"

    click TOOLS "https://github.com/adhilgafoor00-stack/spektra/blob/main/core/tools.py"
    click MEM "https://github.com/adhilgafoor00-stack/spektra/blob/main/core/memory.py"
    click LEARN "https://github.com/adhilgafoor00-stack/spektra/blob/main/core/learn.py"
    click WDG "https://github.com/adhilgafoor00-stack/spektra/blob/main/core/widgets.py"

    click SK_INIT "https://github.com/adhilgafoor00-stack/spektra/blob/main/skills/__init__.py"
    click SK_GEN "https://github.com/adhilgafoor00-stack/spektra/blob/main/skills/general.py"
    click SK_FM "https://github.com/adhilgafoor00-stack/spektra/blob/main/skills/file_manager.py"

    click UIHTML "https://github.com/adhilgafoor00-stack/spektra/blob/main/templates/index.html"
    click C_HTML "https://github.com/adhilgafoor00-stack/spektra/blob/main/templates/index.html"

    click UIJS "https://github.com/adhilgafoor00-stack/spektra/blob/main/static/js/app.js"
    click C_JS "https://github.com/adhilgafoor00-stack/spektra/blob/main/static/js/app.js"

    click UICSS "https://github.com/adhilgafoor00-stack/spektra/blob/main/static/css/styles.css"
    click C_CSS "https://github.com/adhilgafoor00-stack/spektra/blob/main/static/css/styles.css"

    click MEMJSON "https://github.com/adhilgafoor00-stack/spektra/blob/main/data/memory.json"
    click FACTSJSON "https://github.com/adhilgafoor00-stack/spektra/blob/main/data/facts.json"

    click REQ "https://github.com/adhilgafoor00-stack/spektra/blob/main/requirements.txt"

    click DFS "https://github.com/adhilgafoor00-stack/spektra/tree/main/skills/"
    click OSFS "https://github.com/adhilgafoor00-stack/spektra/tree/main/skills/"

    %%========================
    %% Styles
    %%========================
    classDef frontend fill:#D6F5D6,stroke:#1B7F3A,stroke-width:1px,color:#0B2E13
    classDef backend fill:#D6E8FF,stroke:#1E5AA8,stroke-width:1px,color:#0B1E3A
    classDef datastore fill:#FFE6B3,stroke:#B26A00,stroke-width:1px,color:#4A2B00
    classDef external fill:#E8E8E8,stroke:#666,stroke-width:1px,color:#222
    classDef note fill:#FFF2CC,stroke:#B7A100,stroke-width:1px,color:#3A3300
    classDef config fill:#F0D9FF,stroke:#6B2FA3,stroke-width:1px,color:#2B0F3F
```
