# nooqta/saiku architecture

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

- Interactive diagram: https://gitdiagram.com/nooqta/saiku
- Repository: https://github.com/nooqta/saiku

## Overview

##### Main Components
- Core Engine & Agent: At the heart of Saiku is the “Agent” system. This is represented by the files in src/agents (such as agent.ts, planningAgent.ts, workerAgent.ts) and the core logic in src/index.ts.
- Action Modules: The actions in src/actions (like chat, calendar, file, web request, etc.) form the functional “toolbox” that the agent can invoke. Represent each action module as a component that encapsulates specific functionalities.
- CLI and Command Handler: The src/bin folder contains the CLI entry point (cli.ts) and subsequent commands (for actions, autopilot, serve, etc.). This layer acts as one of the interfaces by which users interact with the system.
- LLM Adapters: The src/llms folder (with adapters for OpenAI, Claude, Google Vertex, Ollama, etc.) provides the abstraction layer to interact with different language models.
- Extensions (Integrations/UI): There are two separate extension projects:
– The "ai-chatbot" extension in extensions/ai-chatbot is built using a Next.js-like app structure (with pages, api routes, components, etc.) to provide a web-based chat UI.
– The "chrome" extension in extensions/chrome that provides a browser-integrated interface.
- Frontend Components: Within the “ai-chatbot” extension, there is a clear separation between layout (globals.css, layout.tsx), pages (chat, sign-in, share, etc.), and UI components (buttons, alerts, sidebars) that are used to deliver a modern interactive UI.
- External Service Integrations: Components or modules (in src/services and optional integrations in the README such as Google Vision, Calendar, etc.) represent connections to external APIs and services. Label these as external dependencies (e.g., OpenAI API, Google Cloud Vision, etc.).

##### Relationships and Data Flow
- The CLI/Command Handler calls the Core Agent.
- The Core Agent decides which Action Modules to invoke based on user commands or interactions.
- Action Modules may require LLM outputs; thus, the Agent contacts one of the LLM Adapters.
- The Agent also interfaces with external services and APIs.
- For web-based interactions, the ai-chatbot extension’s frontend components make REST or API calls (via its routes in app/api) to the agent’s logic.
- The Chrome extension similarly bridges browser user inputs with Saiku’s core processing.

##### Architectural Patterns & Principles
- Modular & Extensible Design: Emphasize that both action modules and integrations (LLMs, external services) are separate, making the system extensible.
- Plugin Architecture: The extensions like AI Chatbot and Chrome support different “clients” of the core engine.
- Separation of Concerns: Distinguish between the presentation layer (frontend extensions), business logic (agent and actions), external API integration (LLM adapters and services), and CLI command handling.
- Use of the PEAS Framework: The system is structured around sensors (inputs from CLI/UI), performance evaluation, and actuators (actions executed).

##### Technology/Framework Details
- Next.js (or similar React-based framework) in the ai-chatbot extension.
- Node.js and TypeScript across the project’s codebase.
- External APIs: OpenAI, Google Cloud (Vision and Calendar), and additional third-party integrations.
- Integration of ESLint, Prettier, Tailwind CSS (within the UI components for the chatbot).

##### Capturing Essential Architectural Elements
- User interfaces (CLI, web UI, Chrome extension),
- The modular agent with its actions and planning/worker agents,
- Integration with language models via adapters,
- External API integration modules.
- That data flows (input → processing → output) are clearly mapped out from each entry point to final action results.

This step-by-step approach will provide clarity to any engineer looking to understand or further develop Saiku’s system architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        CLI("CLI Interface"):::ui
        Chat("AI Chatbot UI"):::ui
        Chrome("Chrome Extension UI"):::ui
    end

    subgraph "Core Processing"
        Agent("Core Agent Engine"):::core
        AgentEntry("Core Entry Point"):::core
        Actions("Action Modules"):::core
        Adapters("LLM Adapters"):::core
    end

    External("External Service Integrations"):::external

    %% Data Flow from User Interfaces to Core Processing
    CLI -->|"sendsInput"| Agent
    Chat -->|"sendsInput"| Agent
    Chrome -->|"sendsInput"| Agent

    %% Core Agent interactions
    Agent -->|"invokes"| Actions
    Agent -->|"calls"| Adapters
    Agent -->|"integrates"| External
    Agent -->|"initializes"| AgentEntry

    %% Additional interactions from Modules to External Services
    Actions -->|"calls"| External
    Adapters -->|"calls"| External

    %% Styles
    classDef ui fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/nooqta/saiku/tree/main/src/bin"
    click Chat "https://github.com/nooqta/saiku/tree/main/extensions/ai-chatbot"
    click Chrome "https://github.com/nooqta/saiku/tree/main/extensions/chrome"
    click Agent "https://github.com/nooqta/saiku/tree/main/src/agents"
    click AgentEntry "https://github.com/nooqta/saiku/blob/main/src/index.ts"
    click Actions "https://github.com/nooqta/saiku/tree/main/src/actions"
    click Adapters "https://github.com/nooqta/saiku/tree/main/src/llms/adapters"
    click External "https://github.com/nooqta/saiku/tree/main/src/services"
```
