# pratham15541/shellmind architecture

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

- Interactive diagram: https://gitdiagram.com/pratham15541/shellmind
- Repository: https://github.com/pratham15541/shellmind

## Overview

##### Project Type & Purpose
- Project Type: Full-stack CLI application (JavaScript/Node.js).
- Purpose: Provide a terminal-based AI chatbot experience with session management and file-attachment capabilities, powered by an external AI API.

##### File Structure
- bin/main.js – CLI entrypoint (triggered by `npm link`/shebang).
- src/cli – Core CLI modules:
– cli.js: parses commands & flags
– handleQuestionLoop.js: main REPL loop
– selectFile.js: file-picker integration
– sessionManager.js: create/resume sessions
- src/api – External API client:
– api.js: HTTP calls to AI service
– fileManager.js: reads/serializes file content
- src/utils – Shared helpers:
– chatHistory.js: store/retrieve conversation log
– stateManager.js: in-memory state
– systemInstruction.js: contains prompt templates
- src/configs/env.js – environment/config loader
- src/index.js – orchestrates initialization & module wiring
- rollup.config.js & build scripts – packaging into bin/main.js

##### README Insights
- Key features: session management, file selection, cross-platform CLI.
- Usage: global npm install, `shellmind` commands.

a. Main Components
1. User Terminal (CLI)
2. CLI Controller Layer
- Command Parser (cli.js)
- REPL Loop (handleQuestionLoop.js)
- Session Manager (sessionManager.js)
- File Selector (selectFile.js)
3. Core Services
- State Manager & Chat History (stateManager.js, chatHistory.js)
- System Instruction Provider (systemInstruction.js)
4. API Layer
- AI Client (api.js)
- File Manager (fileManager.js)
5. External AI Service (e.g., OpenAI)
6. Configuration
- Env Loader (env.js)
7. Build & Distribution
- Rollup Bundler & npm publish pipeline

b. Relationships & Data Flows
- User types command → CLI Controller
- Controller invokes Session Manager → loads previous history via Chat History
- User input (and attached file content via File Selector + File Manager) → System Instruction → API Client
- API Client sends HTTP request to External AI Service → receives response
- Response → passed back to REPL Loop → displayed in terminal → appended to Chat History & in-memory State Manager
- Config Loader provides API keys & settings at startup
- Bundler and npm pipelines are build-time components (separate deployment flank)

c. Architectural Patterns & Principles
- Layered Architecture:
- Presentation Layer (CLI)
- Application Layer (session, commands)
- Domain/Utility Layer (state, history, prompts)
- Infrastructure Layer (API, file I/O, config)
- Single Responsibility: each module handles one piece of functionality
- Dependency Injection-like wiring in src/index.js
- Stateless API client; state is managed locally

d. Key Technologies
- Node.js + Commander.js/yargs (assumed) for CLI parsing
- fetch/axios or native HTTPS for API calls
- Rollup for bundling into a single executable script
- .env for config, npm for package management

##### Final Checklist
- Clear component labels matching directory/module names
- Notes for critical design decisions (e.g., “Chat history persisted in JSON files or memory”)
- Build/deploy flow separately at the bottom or side

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UserTerminal["User Terminal (CLI Entrypoint)"]:::presentation
        CommandParser["Command Parser (cli.js)"]:::presentation
        REPLLoop["REPL Loop (handleQuestionLoop.js)"]:::presentation
        SessionMgrCtrl["Session Manager (sessionManager.js)"]:::presentation
        FileSelector["File Selector (selectFile.js)"]:::presentation
    end

    %% Application Orchestrator
    subgraph "Application Orchestrator"
        direction TB
        AppOrchestrator["Orchestrator & Wiring (src/index.js)"]:::application
    end

    %% Domain/Utility Layer
    subgraph "Domain/Utility Layer"
        direction TB
        StateMgr["State Manager (stateManager.js)"]:::domain
        ChatHistory["Chat History Storage (chatHistory.js)"]:::domain
        SysInstruction["System Instruction Provider (systemInstruction.js)"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        ConfigLoader["Configuration Loader (env.js)"]:::infrastructure
        APIClient["AI Client (api.js)"]:::infrastructure
        FileManager["File Manager (fileManager.js)"]:::infrastructure
    end

    %% External Service
    subgraph "External"
        direction TB
        ExternalAI["External AI Service"]:::external
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        Bundler["Rollup Bundler (rollup.config.js)"]:::deployment
    end

    %% Data Flows
    UserTerminal -->|"invoke"| AppOrchestrator
    AppOrchestrator -->|"parseCommand()"| CommandParser
    CommandParser -->|"startREPL()"| REPLLoop
    CommandParser -->|"initSession()"| SessionMgrCtrl
    SessionMgrCtrl -->|"loadHistory()"| ChatHistory
    REPLLoop -->|"getUserInput()"| FileSelector
    FileSelector -->|"selectFile()"| FileManager
    REPLLoop -->|"buildPrompt()"| SysInstruction
    SysInstruction -->|"prompt"| APIClient
    APIClient -->|"sendRequest()"| ExternalAI
    ExternalAI -->|"response"| APIClient
    APIClient -->|"deliverResponse()"| REPLLoop
    REPLLoop -->|"append()"| ChatHistory
    REPLLoop -->|"updateState()"| StateMgr

    %% Config and Deployment
    ConfigLoader -.->|"loadEnv()"| AppOrchestrator
    Bundler -.->|"bundle src/index.js"| UserTerminal

    %% Click Events
    click UserTerminal "https://github.com/pratham15541/shellmind/blob/main/bin/main.js"
    click CommandParser "https://github.com/pratham15541/shellmind/blob/main/src/cli/cli.js"
    click REPLLoop "https://github.com/pratham15541/shellmind/blob/main/src/cli/handleQuestionLoop.js"
    click SessionMgrCtrl "https://github.com/pratham15541/shellmind/blob/main/src/cli/sessionManager.js"
    click FileSelector "https://github.com/pratham15541/shellmind/blob/main/src/cli/selectFile.js"
    click StateMgr "https://github.com/pratham15541/shellmind/blob/main/src/utils/stateManager.js"
    click ChatHistory "https://github.com/pratham15541/shellmind/blob/main/src/utils/chatHistory.js"
    click SysInstruction "https://github.com/pratham15541/shellmind/blob/main/src/utils/systemInstruction.js"
    click APIClient "https://github.com/pratham15541/shellmind/blob/main/src/api/api.js"
    click FileManager "https://github.com/pratham15541/shellmind/blob/main/src/api/fileManager.js"
    click ConfigLoader "https://github.com/pratham15541/shellmind/blob/main/src/configs/env.js"
    click AppOrchestrator "https://github.com/pratham15541/shellmind/blob/main/src/index.js"
    click Bundler "https://github.com/pratham15541/shellmind/blob/main/rollup.config.js"

    %% Styles
    classDef presentation fill:#D6EAF8,stroke:#21618C,stroke-width:1px
    classDef application fill:#D5F5E3,stroke:#229954,stroke-width:1px
    classDef domain fill:#FCF3CF,stroke:#B7950B,stroke-width:1px
    classDef infrastructure fill:#FADBD8,stroke:#C0392B,stroke-width:1px
    classDef external fill:#E8DAEF,stroke:#7D3C98,stroke-width:1px
    classDef deployment fill:#F2F3F4,stroke:#7B7D7D,stroke-width:1px
```
