# pranav-kunjir/swift-terminal architecture

> Architecture diagram of the GitHub repository pranav-kunjir/swift-terminal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pranav-kunjir/swift-terminal
- Repository: https://github.com/pranav-kunjir/swift-terminal

## Overview

##### Project type and purpose
- This is a desktop AI-powered terminal application built with Electron (Node.js + Chromium).
- Purpose: accept a natural-language prompt, call an AI service, receive shell commands in response, display them to the user, and optionally execute them in the console.

##### File structure
Top-level files
- package.json / package-lock.json – defines dependencies and entry points
- main.js – Electron “main” process bootstrap
- preload.js – Electron preload script to expose safe APIs to the renderer
- renderer.js – UI logic that runs in the browser context
- index.html / index.js – front-end entry (index.js may wire up events in renderer)
- src/
– css/style.css – UI styling
– module/
- handle-ai.js – business logic for calling the AI API
- handle-chat.js – logic for managing chat sessions (persisting to disk)
- USERDATA/ – local storage for chat logs (e.g., USERDATA/chats/test.json)
- ins/ – (possibly installation scripts or assets)
- todo.txt – developer notes

##### Extract additional insights from README
- “An AI terminal that takes in prompt and give back commands to run in console”
- Implies integration with an external AI service (OpenAI or similar), local persistence of chat history, and execution or display of shell commands.

a. Main components
- Electron Main Process (main.js)
- Preload Script (preload.js)
- Renderer Process (UI: index.html + renderer.js + CSS/images)
- AI Module (handle-ai.js)
- Chat Module (handle-chat.js + USERDATA storage)
- External AI Service (e.g., OpenAI API)
- OS Shell / Command Executor (Node child_process)

b. Relationships & data flow
1. User types prompt in the Renderer UI →
2. Renderer calls a secure IPC method exposed by Preload →
3. Main Process receives IPC call →
4. Main Process invokes handle-chat to append the prompt to chat history →
5. Main Process invokes handle-ai, which issues HTTP request to External AI Service →
6. AI returns generated shell commands →
7. Main Process may pass commands back via IPC to Renderer for display, and/or to the OS Shell executor for execution →
8. handle-chat logs the response in USERDATA →
9. Renderer displays AI suggestions and execution results to the user.

c. Architectural patterns & principles
- Separation of concerns: UI vs. business logic vs. persistence vs. external integration
- IPC boundary: using Preload to enforce security between untrusted renderer and Node APIs
- Modularization: distinct modules for AI integration and chat management
- Persistence abstraction: storing chat logs in a data folder

d. Key technologies
- Electron (main, preload, renderer processes)
- Node.js (file system, child_process, HTTP)
- HTML/CSS/JavaScript for the front end
- OpenAI or equivalent AI HTTP API
- JSON file storage for user data

##### Detail without over-splitting
- Critical parts (UI, IPC, modules, external API, storage, shell)
- Don’t fragment modules further than “AI” and “Chat” unless there’s additional complexity
- Data flow for both the chat logging path and the AI request/response path

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Desktop App"
        subgraph "Renderer Process"
            UI["Renderer UI\n(index.html)"]:::frontend
            IDX["index.js"]:::frontend
            RDR["renderer.js"]:::frontend
            CSS["style.css"]:::frontend
            IMG["img/"]:::frontend
        end
        PRE["Preload Script"]:::backend
        subgraph "Main Process"
            MAIN["Electron Main Process"]:::backend
            AI["AI Module\n(handle-ai.js)"]:::backend
            CHAT["Chat Module\n(handle-chat.js)"]:::backend
        end
    end

    EX["External AI Service"]:::external
    FS["User Data Storage\n(USERDATA)"]:::storage
    SH["OS Shell Executor"]:::shell
    Pkg["package.json"]:::config

    UI -->|"enters prompt"| RDR
    RDR -->|"IPC invoke"| PRE
    PRE -->|"forward IPC"| MAIN

    MAIN -->|"log prompt"| CHAT
    CHAT -->|"writes to storage"| FS

    MAIN -->|"get commands"| AI
    AI -->|"HTTP request"| EX
    EX -->|"response"| AI
    AI -->|"commands"| MAIN

    MAIN -->|"send results"| PRE
    PRE -->|"IPC response"| RDR
    RDR -->|"display commands"| UI

    MAIN -->|"execute commands"| SH
    SH -->|"execution result"| MAIN

    Pkg --> MAIN

    click MAIN "https://github.com/pranav-kunjir/swift-terminal/blob/main/main.js"
    click PRE "https://github.com/pranav-kunjir/swift-terminal/blob/main/preload.js"
    click UI "https://github.com/pranav-kunjir/swift-terminal/blob/main/index.html"
    click IDX "https://github.com/pranav-kunjir/swift-terminal/blob/main/index.js"
    click RDR "https://github.com/pranav-kunjir/swift-terminal/blob/main/renderer.js"
    click CSS "https://github.com/pranav-kunjir/swift-terminal/blob/main/src/css/style.css"
    click IMG "https://github.com/pranav-kunjir/swift-terminal/tree/main/src/img/"
    click AI "https://github.com/pranav-kunjir/swift-terminal/blob/main/src/module/handle-ai.js"
    click CHAT "https://github.com/pranav-kunjir/swift-terminal/blob/main/src/module/handle-chat.js"
    click FS "https://github.com/pranav-kunjir/swift-terminal/blob/main/USERDATA/chats/test.json"
    click Pkg "https://github.com/pranav-kunjir/swift-terminal/blob/main/package.json"

    classDef frontend fill:#e0ffe0,stroke:#00a000,color:#005000
    classDef backend fill:#e0f0ff,stroke:#0060c0,color:#003080
    classDef external fill:#ffe0f0,stroke:#d08000,color:#804000
    classDef storage fill:#fff0e0,stroke:#c06000,color:#803000
    classDef shell fill:#ffffe0,stroke:#c0c000,color:#808000
    classDef config fill:#f0f0f0,stroke:#909090,color:#505050
```
