# akutishevsky/salesforce-local-llm-assistant architecture

> Architecture diagram of the GitHub repository akutishevsky/salesforce-local-llm-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akutishevsky/salesforce-local-llm-assistant
- Repository: https://github.com/akutishevsky/salesforce-local-llm-assistant

## Overview

##### Project type and purpose
- This is a Salesforce-native, full-stack application built with SFDX (Salesforce DX), Lightning Web Components (LWC) on the front end, and Apex classes on the back end, packaged as a Salesforce “Local LLM Assistant.”
- It embeds a WebAssembly/JavaScript LLM engine (picoLLM.js) as a static resource to run inference locally in the browser, and it uses Salesforce records (custom metadata and custom objects) for prompts and context.

##### File structure
- Top‐level: sfdx-project.json, package.json, jest.config.js (project config and test runner).
- force-app/main/default:
- classes/ – Apex controllers (ModalAssistantSelect*, PicklistLocalLLMAgentSettings, RecordSelector, RecordUtils, SObjectUtils, SystemPromptSelector) plus unit tests.
- lwc/ – multiple LWC components: assistant, assistantChat, assistantHeader, assistantPublisher, and configuration & selection modals.
- objects/ – Custom Metadata Type Local_LLM_Assistant_Setting__mdt and custom object System_Prompt__c for system prompts.
- staticresources/ – picoLLM.js static resource that loads and runs the local LLM.
- pages/ – a Visualforce page (PicollmWeb.page) for legacy/demo embedding.
- layouts/ and tabs/ – configuration to expose System_Prompt__c in the UI.

##### README for additional insights
- Purpose: “LWC that runs LLMs locally on your computer and uses Salesforce records for context.”
- Setup: Deploy code, configure API key in custom metadata, drop component on any Lightning page.
- Dependencies: picovoice.ai for model download & API key; Salesforce LWC & Apex runtime.

##### Capturing essential architectural elements
- Be exhaustive: show all the modals and controllers as part of the configuration flow.
- Data stores: custom metadata vs. custom object vs. user records.
- Real-time inference path: UI → picoLLM → UI.
- Don’t over-complicate: focus on logical layers (UI, Data Service, Persistence, External).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Browser)"
        direction TB
        subgraph "LWC Bundle"
            direction TB
            A1["assistant LWC"]:::frontend
            A2["assistantChat"]:::frontend
            A3["assistantHeader"]:::frontend
            A4["assistantPublisher"]:::frontend
            subgraph "Modals"
                direction TB
                M1["modalAssistantConfiguration"]:::frontend
                M2["modalAssistantSelectRecordFields"]:::frontend
                M3["modalAssistantSelectRelatedRecords"]:::frontend
                M4["modalAssistantSystemPrompt"]:::frontend
            end
        end
        SR["picoLLM.js (Local LLM Engine)"]:::frontend
    end

    %% Server Side
    subgraph "Salesforce Platform"
        direction TB
        subgraph "Apex Controllers"
            direction TB
            C1["ModalAssistantSelectRecordFieldsCtrl"]:::backend
            C2["ModalAssistantSelectRelatedRecordsCtrl"]:::backend
            C3["ModalSystemPromptCtrl"]:::backend
            C4["PicklistLocalLLMAgentSettings"]:::backend
            C5["RecordSelector"]:::backend
            C6["RecordUtils"]:::backend
            C7["SObjectUtils"]:::backend
            C8["SystemPromptSelector"]:::backend
        end
        subgraph "Data Layer"
            direction TB
            D1["Local_LLM_Assistant_Setting__mdt"]:::db
            D2["System_Prompt__c"]:::db
        end
    end

    %% External
    EX["Picovoice API"]:::external

    %% User Interaction
    User["User"]:::external

    %% Connections
    User -->|"opens Lightning page"| A1
    A1 -->|"@AuraEnabled: fetch records"| C5
    A1 -->|"@AuraEnabled: fetch prompts"| C8
    A1 -->|"@AuraEnabled: fetch settings"| C4
    A1 --> C1
    A1 --> C2
    A1 --> C3
    C5 -->|"reads prompts"| D2
    C8 -->|"loads prompts"| D2
    C4 -->|"reads settings"| D1
    A1 -->|"load model"| SR
    A1 -->|"run inference"| SR
    SR -->|"return response"| A2
    SR -.->|"download model (setup)"| EX

    %% Click Events
    click A1 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/assistant/assistant.js"
    click A2 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/assistantChat/assistantChat.js"
    click A3 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/assistantHeader/assistantHeader.js"
    click A4 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/assistantPublisher/assistantPublisher.js"
    click M1 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/modalAssistantConfiguration/modalAssistantConfiguration.js"
    click M2 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/modalAssistantSelectRecordFields/modalAssistantSelectRecordFields.js"
    click M3 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/modalAssistantSelectRelatedRecords/modalAssistantSelectRelatedRecords.js"
    click M4 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/lwc/modalAssistantSystemPrompt/modalAssistantSystemPrompt.js"
    click SR "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/staticresources/picoLLM.js"
    click C1 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/ModalAssistantSelectRecordFieldsCtrl.cls"
    click C2 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/ModalAssistantSelectRelatedRecordsCtrl.cls"
    click C3 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/ModalSystemPromptCtrl.cls"
    click C4 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/PicklistLocalLLMAgentSettings.cls"
    click C5 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/RecordSelector.cls"
    click C6 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/RecordUtils.cls"
    click C7 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/SObjectUtils.cls"
    click C8 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/classes/SystemPromptSelector.cls"
    click D1 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/customMetadata/Local_LLM_Assistant_Setting.Setting.md-meta.xml"
    click D2 "https://github.com/akutishevsky/salesforce-local-llm-assistant/blob/main/force-app/main/default/objects/System_Prompt__c/System_Prompt__c.object-meta.xml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#0D5302
    classDef db fill:#FFF3E0,stroke:#FF6F00,color:#E65100
    classDef external fill:#ECEFF1,stroke-dasharray: 5 5,stroke:#546E7A,color:#263238
    class User,EX external
```
