# avijeett007/knotie-ai architecture

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

- Interactive diagram: https://gitdiagram.com/avijeett007/knotie-ai
- Repository: https://github.com/avijeett007/knotie-ai

## Overview

##### Project type and purpose
- Knotie-AI is a full-stack, open-source inbound/outbound AI Sales Agent.
- It consists of a Python/Flask web application with a minimal frontend (Jinja templates), a modular AI orchestration layer, a conversation caching subsystem, and integrations with external services (OpenAI API, Twilio, third-party tools).

##### File structure
- Top-level entrypoints:
- app.py (Flask server)
- Dockerfile & docker-compose*.yml (containerization & multi-service orchestration)
- Frontend:
- templates/index.html (public UI)
- templates/admin.html (admin UI)
- Backend modules:
- ai_helpers.py, audio_helpers.py, appUtils.py (core utilities & wrappers)
- prompts.py, stages.py, tools.py, tools_helper.py (AI prompt orchestration & tool/plugin layer)
- ConversationCache/ (state management package, uses Redis via CacheManager.py)
- Model training:
- Ai_Model_Training/… (scripts to prepare JSONL & train OpenAI models)
- Config & deployment:
- config.py, .env_sample (configuration)
- .github/workflows/*.yml (CI/CD pipelines)
- openapi_specs/ (future OpenAPI/Swagger support)
- Docs:
- docs/ (installation, deployment, how-to guides)

##### README for additional insights
- Confirms Python/Flask, Redis cache, OpenAI integration, Twilio support, Dockerized deployment, and an admin UI.
- Future features hint at plugin-style tool integration and OpenAPI spec support.

##### Main components & their relationships
a. Client Layer
- Web Browser → HTTP/WS → Flask server
- Uses index.html (public) or admin.html (admin UI)
b. Web/API Layer (Flask)
- Routes in app.py invoke appUtils, ai_helpers, audio_helpers
- Exposes REST/Webhook endpoints for external systems
c. Conversation Cache
- ConversationCache.CacheManager (Redis backend)
- Decorators enforce singleton, config loaded from Configuration.py
d. AI Orchestration Layer
- prompts.py & stages.py: define prompt templates & multi-step flows
- tools.py & tools_helper.py: plugin architecture for calling external APIs (Twilio, third-party tools)
- ai_helpers.py: wrapper around OpenAI API calls
e. Persistence & Messaging
- Redis (state/cache) via docker-compose
- File-based logs or .jsonl training data in Ai_Model_Training
f. External Services
- OpenAI API (chat completion, embeddings)
- Twilio (SMS/Voice)
- Future: other SaaS via plugin modules
g. DevOps / CI-CD
- Dockerfile & docker-compose (local dev, prod deploy, Redis only)
- GitHub Actions (build, test, docker image publish)
- retype.yml & retype.json (documentation site generation)

##### Architectural patterns & design principles
- Layered MVC-style separation: Presentation (templates) → Controller (Flask routes) → Model/Service (AI orchestration & cache)
- Plugin/Strategy pattern for external tools
- Singleton pattern for cache manager
- Containerized micro-services style (Flask app + Redis)

##### Essential elements
- Clear component names:
- Client UI, Flask Server, ConversationCache, AI Orchestrator, External Services
- Data flows & dependencies: annotate with “prompt data,” “cache lookup,” “AI response,” etc.
- Technology callouts: Python/Flask, Jinja2, Redis, OpenAI API, Docker, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Tier"
        Browser["Client Browser"]:::frontend
    end

    subgraph "Application Tier"
        subgraph "Flask Server"
            direction TB
            Routes["app.py"]:::internal
            subgraph "Templates"
                direction TB
                PublicUI["index.html"]:::internal
                AdminUI["admin.html"]:::internal
            end
            subgraph "Utilities & Wrappers"
                direction TB
                Utils["appUtils.py"]:::internal
                AIHelper["ai_helpers.py"]:::internal
                AudioHelper["audio_helpers.py"]:::internal
            end
            subgraph "AI Orchestration"
                direction TB
                Prompts["prompts.py"]:::internal
                Stages["stages.py"]:::internal
                Tools["tools.py"]:::internal
                ToolsHelper["tools_helper.py"]:::internal
            end
            subgraph "Conversation Cache Interface"
                direction TB
                CacheMgr["CacheManager.py"]:::cache
                SingletonDec["decorators/singleton.py"]:::cache
                ConfigLoader["environment/Configuration.py"]:::cache
            end
        end
    end

    subgraph "Data & External Tier"
        Redis["Redis"]:::database
        subgraph "External Services"
            direction TB
            OpenAI["OpenAI API"]:::externalService
            Twilio["Twilio"]:::externalService
            FutureTools["Future Plugin APIs"]:::externalService
        end
    end

    Browser -->|"HTTP/WS"| Routes
    Routes -->|"serves"| PublicUI
    Routes -->|"serves"| AdminUI
    Routes -->|"uses"| Utils
    Routes -->|"uses"| AIHelper
    Routes -->|"uses"| AudioHelper
    Routes -->|"orchestrates"| Prompts
    Routes -->|"flows through"| Stages
    Routes -->|"invokes plugins"| Tools
    Tools -->|"registry via"| ToolsHelper
    Routes -->|"cache lookup"| CacheMgr
    CacheMgr -->|"singleton"| SingletonDec
    CacheMgr -->|"config from"| ConfigLoader
    Routes -->|"cache store"| Redis
    AIHelper -->|"calls"| OpenAI
    Tools -->|"calls"| Twilio
    ToolsHelper -->|"future calls"| FutureTools

    click Routes "https://github.com/avijeett007/knotie-ai/blob/develop/app.py"
    click PublicUI "https://github.com/avijeett007/knotie-ai/blob/develop/templates/index.html"
    click AdminUI "https://github.com/avijeett007/knotie-ai/blob/develop/templates/admin.html"
    click Utils "https://github.com/avijeett007/knotie-ai/blob/develop/appUtils.py"
    click AIHelper "https://github.com/avijeett007/knotie-ai/blob/develop/ai_helpers.py"
    click AudioHelper "https://github.com/avijeett007/knotie-ai/blob/develop/audio_helpers.py"
    click Prompts "https://github.com/avijeett007/knotie-ai/blob/develop/prompts.py"
    click Stages "https://github.com/avijeett007/knotie-ai/blob/develop/stages.py"
    click Tools "https://github.com/avijeett007/knotie-ai/blob/develop/tools.py"
    click ToolsHelper "https://github.com/avijeett007/knotie-ai/blob/develop/tools_helper.py"
    click CacheMgr "https://github.com/avijeett007/knotie-ai/blob/develop/ConversationCache/CacheManager.py"
    click SingletonDec "https://github.com/avijeett007/knotie-ai/blob/develop/ConversationCache/decorators/singleton.py"
    click ConfigLoader "https://github.com/avijeett007/knotie-ai/blob/develop/ConversationCache/environment/Configuration.py"

    classDef frontend fill:#eeeeee,stroke:#666666,stroke-width:1px
    classDef internal fill:#BBE1FA,stroke:#1B4965,stroke-width:1px
    classDef cache fill:#D0F4DE,stroke:#1A936F,stroke-width:1px
    classDef database fill:#95D5B2,stroke:#40916C,stroke-width:1px,shape:cylinder
    classDef externalService fill:#F6A6B2,stroke:#9D0208,stroke-width:1px,shape:cloud
```
