# alfrescolabs/alfresco-ai-assistants architecture

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

- Interactive diagram: https://gitdiagram.com/alfrescolabs/alfresco-ai-assistants
- Repository: https://github.com/alfrescolabs/alfresco-ai-assistants

## Overview

##### Project Overview & Main Purpose
- The repository hosts two distinct AI assistant applications for Alfresco:
- Alfresco Docs Bot – focuses on ingesting Alfresco documentation and answering queries based solely on this content.
- Alfresco AI Assistant – interacts with a live Alfresco Content Services (ACS) instance, supporting complex workflows such as search, document transformation, redaction, report generation, etc.
- Both applications rely on an underlying Language Model (LLM), with Ollama as the primary choice, and are containerized using Docker/Docker Compose with provisions for Kubernetes deployments.

##### Key Components Based on the File Tree and README
a. User Interfaces:
- Two separate web UIs, one for each application:
- Docs Bot UI at http://localhost:8503.
- AI Assistant UI at http://localhost:8504.
b. Application Backend (Python Programs):
- alfresco_docs_bot.py for the Docs Bot.
- alfresco_ai_assistant.py for the AI Assistant.
- Additional supporting scripts like alfresco_api.py, commons.py, and report_writer.py.
c. LLM Service:
- A core LLM component (accessed via the LLM service, using Ollama as the containerized backend).
- Environment variables and configuration indicate integration with various LLM options.
d. API & Tools Layer (for Alfresco AI Assistant):
- API endpoints are abstracted into components like discovery-api, search-api, and node-api.
- Tools for auxiliary tasks such as discovery, transformation, and redaction.
e. Database & Data Stores:
- Additionally, a substantial “initial-load” folder provides scripts/instructions to prepare documentation and integration data for the Alfresco Docs Bot.
f. Infrastructure & Deployment:
- Docker-related files (docker-compose.yml, multiple Dockerfiles) to orchestrate service containers.
- Kubernetes configuration files under the “k8s” directory to support production-grade or cloud-based deployments.
- Environment configuration files (env.example) to manage runtime variables, particularly for connectivity with ACS, LLM, Neo4j, and other external services.
g. Auxiliary and Development Assets:
- Supporting documentation (behind_the_scenes.md and docs directory) and demo files for testing.
- Scripts folder includes transformer.py for data preparation.

##### How to Represent These
- Two main application nodes: “Alfresco Docs Bot” and “Alfresco AI Assistant.”
- For AI Assistant, add an “API Layer” node. Within this node, optionally partition subcomponents as “discovery-api,” “search-api,” and “node-api.”
- A “Tools” block for the AI Assistant showing subcomponents like “discovery,” “transform,” and “redact.”
b. Interactions/Relationships:
- From “User” to each UI.
- From each UI to the LLM.
- Within AI Assistant: show the query flow from the LLM to the Tools block, the invocation of API endpoints by the Tools, and the feedback loop from the API back to the LLM, then to the User.
- Interactions with external systems:
- Neo4j database accessible at http://localhost:7474, if used for graph queries.
c. Architectural Patterns:
- Use of containerization and microservices principles (each component in its own container, managed via docker-compose and Kubernetes).
- Separation of concerns: one set of services ingests and transforms documentation for the Docs Bot, while another set provides a robust API and toolset for the live ACS interactions.
- Mention that the LLM acts as a central decision-making service that interfaces with additional tools, reflecting a mediator pattern.
d. Technologies and Frameworks:
- Docker (including Docker Compose and Dockerfiles)
- Kubernetes (for production deployments with YAML configurations)
- Python (the backend services with associated scripts)
- Neo4j (graph database as shown in the environment configuration)
- Ollama LLM (and potential other LLM interfaces, as stated with environment variables)
- Embedding models, potentially using Sentence Transformer or alternatives as indicated by the EMBEDDING_MODEL variable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    User["User"]:::user

    %% Alfresco Docs Bot Subgraph
    subgraph "Alfresco Docs Bot"
        DocsUI["Docs Bot UI (localhost:8503)"]:::ui
        DocsBackend["Docs Bot Backend"]:::backend
        DockerDocs["Docs Bot Docker Config"]:::deployment
        Ingestion["Ingestion Setup"]:::ingestion
        VectorDB["Vector Database"]:::database
    end

    %% Alfresco AI Assistant Subgraph
    subgraph "Alfresco AI Assistant"
        AI_UI["AI Assistant UI (localhost:8504)"]:::ui
        AI_Backend["AI Assistant Backend"]:::backend
        DockerAI["AI Assistant Docker Config"]:::deployment
        API["API Endpoints"]:::api
        Tools["Tools (discovery,transform,redact)"]:::tools
        ACS["ACS Instance"]:::external
        Neo4j["Neo4j Database (localhost:7474)"]:::database
    end

    %% Core LLM Services
    subgraph "Core Services"
        LLM["LLM Service (Ollama)"]:::llm
        Embedding["Embedding Components"]:::llm
        EnvConfig["Environment & Config"]:::config
    end

    %% Deployment & Infrastructure
    subgraph "Infrastructure & Deployment"
        dockerCompose["Docker Compose"]:::deploymentInfra
        k8s["Kubernetes Config"]:::deploymentInfra
        dockerIgnore[".dockerignore"]:::deploymentInfra
    end

    %% API & Tools Additional Layer
    subgraph "API & Tools Layer (Additional for AI Assistant)"
        AuxTools["Auxiliary Tools (commons & report)"]:::apiTools
        Transform["Transformation Tools"]:::apiTools
    end

    %% Auxiliary & Development Assets
    subgraph "Auxiliary & Assets"
        Static["Static UI Assets"]:::assets
        DocsAssets["Documentation (docs & behind_the_scenes)"]:::assets
        DemoFiles["Demo Files"]:::assets
        GitIgnore[".gitignore"]:::assets
    end

    %% Connections - User interactions
    User -->|"accesses"| DocsUI
    User -->|"accesses"| AI_UI

    %% Docs Bot flow
    DocsUI -->|"sends_query"| DocsBackend
    DocsBackend -->|"invokes"| LLM
    LLM -->|"retrieves_data"| VectorDB
    VectorDB -->|"provides_data"| LLM
    LLM -->|"returns_response"| DocsUI

    %% AI Assistant flow
    AI_UI -->|"sends_query"| AI_Backend
    AI_Backend -->|"invokes"| LLM
    LLM -->|"calls_tools"| Tools
    Tools -->|"executes"| API
    API -->|"communicates_with"| ACS
    API -->|"queries"| Neo4j
    ACS -->|"returns_data"| API
    API -->|"returns_results"| LLM
    LLM -->|"responds"| AI_UI
    
    %% AI Assistant internal integrations
    AI_Backend -->|"integrates"| API
    AI_Backend -->|"utilizes"| AuxTools
    AuxTools -->|"assists"| Transform

    %% LLM internal connections
    LLM ---|"integrates"| Embedding
    LLM ---|"configured_by"| EnvConfig
    DocsBackend ---|"configured_by"| EnvConfig

    %% Deployment connections
    dockerCompose -->|"orchestrates"| DocsBackend
    dockerCompose -->|"orchestrates"| AI_Backend
    k8s -->|"manages"| dockerCompose

    %% Click Events for Component Mapping
    click DocsBackend "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/alfresco_docs_bot.py"
    click DockerDocs "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/alfresco_docs_bot.Dockerfile"
    click Ingestion "https://github.com/alfrescolabs/alfresco-ai-assistants/tree/main/initial-load"
    
    click AI_Backend "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/alfresco_ai_assistant.py"
    click DockerAI "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/alfresco_ai_assistant.Dockerfile"
    
    click API "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/alfresco_api.py"
    click AuxTools "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/commons.py"
    click Transform "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/scripts/transformer.py"
    
    click Embedding "https://github.com/alfrescolabs/alfresco-ai-assistants/tree/main/embedding_model"
    click EnvConfig "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/env.example"
    
    click dockerCompose "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/docker-compose.yml"
    click k8s "https://github.com/alfrescolabs/alfresco-ai-assistants/tree/main/k8s"
    click dockerIgnore "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/.dockerignore"
    
    click Static "https://github.com/alfrescolabs/alfresco-ai-assistants/tree/main/static"
    click DocsAssets "https://github.com/alfrescolabs/alfresco-ai-assistants/tree/main/docs"
    click DemoFiles "https://github.com/alfrescolabs/alfresco-ai-assistants/tree/main/demo_files"
    click GitIgnore "https://github.com/alfrescolabs/alfresco-ai-assistants/blob/main/.gitignore"

    %% Styles
    classDef user fill:#ffebcc,stroke:#d2691e,stroke-width:2px;
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef deployment fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef ingestion fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fde2e2,stroke:#a94442,stroke-width:2px;
    classDef llm fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef api fill:#e2d6f3,stroke:#5a2a83,stroke-width:2px;
    classDef tools fill:#fff0f5,stroke:#c2185b,stroke-width:2px;
    classDef config fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef deploymentInfra fill:#e8eaed,stroke:#5f6368,stroke-width:2px;
    classDef apiTools fill:#f9fbe7,stroke:#827717,stroke-width:2px;
    classDef assets fill:#e0f7fa,stroke:#006064,stroke-width:2px;
```
