# sidetrip-ai/ici-core architecture

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

- Interactive diagram: https://gitdiagram.com/sidetrip-ai/ici-core
- Repository: https://github.com/sidetrip-ai/ici-core

## Overview

##### Project Type and Purpose
- Recognize that this is a full-stack modular AI assistant framework.
- The README explains that it supports context, style, personality, and security awareness.
- The core functionality centers on an ingestion pipeline that converts external data into vector representations and a query pipeline that retrieves and assembles contextual responses.

##### File Structure
- Top-Level Components:
- The “ici” directory contains the core modules. Inside, you have subdirectories like “adapters”, “core”, and “utils” which indicate a highly modular design.
- “adapters” are subdivided into components such as chat, controller, embedders, generators, ingestors, loggers, orchestrators, pipelines, preprocessors, prompt_builders, user_id, validators, and vector_stores. Each adapter is responsible for a single concern in the pipeline.
- Configuration and Setup:
- Files like config.yaml, .env.example, setup scripts (setup.sh, setup.bat), and the README indicate clear deployment and configuration guidelines.
- Continuous integration (with .github/workflows) and tests folders (unit and integration testing) are included to ensure quality and maintainability.

##### Key Components and Relationships
- Main Components:
- Ingestion Pipeline: Managed by adapters such as ingestors, preprocessors, and vector_stores. They are responsible for retrieving, cleaning, and storing data (using in-memory or persistent vector databases).
- Query Pipeline: Composed of components such as chat adapters, prompt builders, and generators that process input queries, retrieve context, and use AI models (OpenAI, Anthropic, Ollama) to generate responses.
- Core Interfaces and Utilities: Found in “ici/core/interfaces” (defining contracts for chat history, embedding, generation, etc.) and “ici/utils” (component loading, configuration, state management).
- Inter-component Interactions:
- The main entry point (main.py) ties these components together.
- Data flows from external sources into the ingestion pipeline and then is stored in a vector store. When a user query is received, the query pipeline retrieves the relevant context from the vector store, which then informs the generator (AI model) and returns a styled response.
- Adapters interact with one another using clearly defined interfaces provided by the “core/interfaces” modules.

##### Architectural Patterns and Design Principles
- Modularity: The codebase is divided into well-isolated components (adapters, core interfaces, utilities) that support easy extension.
- Separation of Concerns: Clear distinction between data ingestion and query response pipelines.
- Configurability: Centralized configuration via config.yaml and environment files (.env).
- Plug-and-Play: Framework supports multiple AI model providers and vector storage backends with an adapter-based approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        extData("External Data (Telegram,Twitter,YouTube)"):::external
        aiAPI("AI Model APIs (OpenAI,Anthropic,Ollama)"):::external
    end

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        ingestors("Ingestors"):::ingestion
        preprocessors("Preprocessors"):::ingestion
        vectorStores("Vector Stores"):::ingestion
    end

    %% Core Interfaces and Utilities
    subgraph "Core & Utilities"
        coreInterfaces("Core Interfaces/Contracts"):::core
        utilities("Utilities"):::utilities
        configYaml("Configuration (config.yaml)"):::utilities
        envFile("Configuration (.env.example)"):::utilities
    end

    %% Query Pipeline
    subgraph "Query Pipeline"
        chatAdapters("Chat Adapters"):::query
        promptBuilders("Prompt Builders"):::query
        generators("Generators"):::query
    end

    %% Main Application Entry Point
    mainApp("Main Application Entry (main.py)"):::main

    %% Data Flow Connections
    extData -->|"data-feed"| ingestors
    extData -->|"data-feed"| preprocessors

    ingestors -->|"process-data"| preprocessors
    preprocessors -->|"clean-data"| vectorStores

    vectorStores -->|"store-context"| coreInterfaces
    coreInterfaces -->|"provide-interface"| chatAdapters

    chatAdapters -->|"receive-query"| promptBuilders
    promptBuilders -->|"build-prompt"| generators
    generators -->|"generate-response"| aiAPI

    %% Main App integrates components
    mainApp -->|"init-ingestion"| ingestors
    mainApp -->|"init-query"| chatAdapters
    mainApp -->|"load-interfaces"| coreInterfaces
    mainApp -->|"load-utilities"| utilities
    mainApp -->|"load-config"| configYaml
    mainApp -->|"load-config"| envFile

    %% Click Events
    click ingestors "https://github.com/sidetrip-ai/ici-core/tree/main/ici/adapters/ingestors"
    click preprocessors "https://github.com/sidetrip-ai/ici-core/tree/main/ici/adapters/preprocessors"
    click vectorStores "https://github.com/sidetrip-ai/ici-core/tree/main/ici/adapters/vector_stores"
    click chatAdapters "https://github.com/sidetrip-ai/ici-core/tree/main/ici/adapters/chat"
    click promptBuilders "https://github.com/sidetrip-ai/ici-core/tree/main/ici/adapters/prompt_builders"
    click generators "https://github.com/sidetrip-ai/ici-core/tree/main/ici/adapters/generators"
    click coreInterfaces "https://github.com/sidetrip-ai/ici-core/tree/main/ici/core/interfaces"
    click utilities "https://github.com/sidetrip-ai/ici-core/tree/main/ici/utils"
    click configYaml "https://github.com/sidetrip-ai/ici-core/blob/main/config.yaml"
    click envFile "https://github.com/sidetrip-ai/ici-core/blob/main/.env.example"
    click mainApp "https://github.com/sidetrip-ai/ici-core/blob/main/main.py"

    %% Styles
    classDef ingestion fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef query fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef utilities fill:#F5CBA7,stroke:#B9770E,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef main fill:#D6EAF8,stroke:#5DADE2,stroke-width:2px;
```
