Skip to main content

Architecture Overview

Scope and Method​

This document covers implemented behavior in:

  • Aventora-Assistant
  • domain-chatbot

Evidence was taken from runtime code, DB layers, Docker/deployment files, and auth/integration modules. Items that depend on external infrastructure are labeled as not verifiable from repository code alone.

High-Level Components (Confirmed)​

  • Engagement Hub API server (FastAPI): Aventora-Assistant/server/server.py
  • Engagement Hub bot runtime for voice/SMS logic: Aventora-Assistant/bot/bot.py, Aventora-Assistant/bot/sms_bot.py
  • Domain Chatbot API server (FastAPI): domain-chatbot/LLM_full/main.py
  • Domain Chatbot Agent/WebSocket/telephony runtime: domain-chatbot/Agent/main.py, domain-chatbot/Agent/server/websocket.py, domain-chatbot/Agent/phone/webhook.py
  • PostgreSQL-backed persistence in both systems:
    • Hub: schema registry and managers in Aventora-Assistant/db/schema_registry.py, Aventora-Assistant/db/*.py
    • Domain Chatbot: runtime DB init/migrations in domain-chatbot/LLM_full/db_operations.py

Main Runtime Technologies (Confirmed)​

  • Python 3.11 containers:
    • Aventora-Assistant/Dockerfile
    • domain-chatbot/Dockerfile
    • domain-chatbot/Dockerfile.agent
  • FastAPI/Uvicorn service model:
    • Aventora-Assistant/run_server.py
    • domain-chatbot/run_api.py
  • PostgreSQL via psycopg2 connection pools in both systems:
    • Aventora-Assistant/db/account_manager.py, Aventora-Assistant/db/user_manager.py
    • domain-chatbot/LLM_full/database_config.py, domain-chatbot/LLM_full/db_operations.py

Backend Services (Confirmed)​

Aventora-Assistant​

  • Modular routers for auth, calls, SMS, accounts, integrations, inbound, and dashboard:
    • Aventora-Assistant/server/server.py
    • Router modules in Aventora-Assistant/server/routers/
  • Startup workers:
    • bulk-call worker, timeout worker, email pull worker, agent email worker, outbound integration health monitor
    • Aventora-Assistant/server/server.py startup event

domain-chatbot​

  • API routers for auth/query/index/submissions/reports/etc.:
    • domain-chatbot/LLM_full/main.py
  • Agent channel support for WebRTC, WebSocket, phone, WhatsApp, Instagram, Telegram:
    • domain-chatbot/Agent/server/*.py, domain-chatbot/Agent/phone/*.py, domain-chatbot/Agent/whatsapp/*.py

Frontend/Client Interaction Surface (Confirmed)​

  • Admin/client apps are external to this scope; repositories expose APIs and WebSockets consumed by web/mobile clients.
  • Domain Chatbot CORS and origin regex controls are in domain-chatbot/LLM_full/main.py and domain-chatbot/LLM_full/settings.py.
  • Hub currently allows all CORS origins (allow_origins=["*"]) in Aventora-Assistant/server/server.py.

Data Stores (Confirmed)​

  • PostgreSQL tables include (non-exhaustive):
    • Hub: accounts, users, api_keys, call_logs, sms_sessions, inbound_secure_links, call_history (Aventora-Assistant/db/schema_registry.py)
    • Domain Chatbot: users, domains, user_settings, temporary_access_tokens, domain_api_keys, submissions (domain-chatbot/LLM_full/db_operations.py)
  • File-based logs exist in both repos (logs/), with rotating handlers:
    • Aventora-Assistant/server/server.py
    • domain-chatbot/logging_config.py

External Integrations (Confirmed in Runtime Code)​

  • LLM/AI: OpenAI, Groq
  • Telephony/messaging: Twilio, Telnyx (signature validation helper), WhatsApp (via Twilio), Telegram
  • Calendar/Auth: Microsoft Graph OAuth, Google OAuth
  • Payments/commerce references: Square webhook routes in Hub
  • CRM: Salesforce, FollowUpBoss, and CRM abstraction hooks (HubSpot/Zoho/Dynamics referenced in comments and service wiring)

Primary evidence:

  • Aventora-Assistant/server/server.py
  • Aventora-Assistant/server/routers/*.py
  • domain-chatbot/LLM_full/settings.py
  • domain-chatbot/LLM_full/auth/service.py
  • domain-chatbot/Agent/*

Deployment Model (Confirmed)​

  • Hub containerized service with externalized env and healthcheck:
    • Aventora-Assistant/docker-compose.yml
  • Domain Chatbot has Dockerfiles and deployment packaging script:
    • domain-chatbot/Dockerfile
    • domain-chatbot/Dockerfile.agent
    • domain-chatbot/deploy_to_production.sh

Assumptions (Explicit)​

  • TLS termination, WAF, network segmentation, and secret-injection controls are infrastructure-dependent and not verifiable solely from repository code.
  • The repos assume externally managed ingress and DNS for production hostnames.

Gaps / Risks​

  • Hub CORS is permissive (*) in active server config (Aventora-Assistant/server/server.py).
  • No in-repo proof of hardened reverse proxy headers/HSTS/CSP at edge.
  • No in-repo proof of infrastructure-level network ACLs or container runtime hardening policies.

Mermaid Architecture Diagram​

flowchart LR
  subgraph Client[Clients]
    A1[Admin UI]
    A2[Web/Mobile User]
    A3[Telephony Provider Webhooks]
  end

  subgraph Hub[Aventora-Assistant]
    H1[FastAPI API server]
    H2[Voice/SMS Bot Runtime]
    H3[Background Workers]
    HDB[(PostgreSQL - Hub tables)]
  end

  subgraph DC[domain-chatbot]
    D1[FastAPI API server]
    D2[Agent/WebSocket/WebRTC]
    DDB[(PostgreSQL - Domain tables)]
  end

  subgraph TP[Third Parties]
    T1[OpenAI/Groq]
    T2[Twilio/Telnyx]
    T3[Microsoft/Google]
    T4[CRM providers]
    T5[Email SMTP]
  end

  A1 --> H1
  A2 --> D1
  A2 --> D2
  A3 --> H1
  A3 --> D2

  H1 --> H2
  H1 --> H3
  H1 --> HDB
  H2 --> HDB
  H3 --> HDB

  H1 <--> D1
  D1 --> DDB
  D2 --> DDB

  H1 --> T1
  H2 --> T1
  D1 --> T1
  D2 --> T1

  H1 --> T2
  D2 --> T2
  H1 --> T3
  D1 --> T3
  H1 --> T4
  D1 --> T5