Skip to main content

Data Flow and Trust Boundaries

Confirmed Trust Boundaries​

  1. Public internet to API/webhook endpoints (Hub and domain-chatbot).
  2. API servers to PostgreSQL databases.
  3. API servers to third-party SaaS (Twilio, OpenAI/Groq, OAuth providers, CRM APIs).
  4. Internal service-to-service calls between Hub and domain-chatbot (Bearer/API-key based).

Inbound Request Flows (Confirmed)​

Hub API + telephony inbound​

  • Entry points include general API routes and webhook-like handlers:
    • Aventora-Assistant/server/server.py
    • Aventora-Assistant/server/routers/inbound.py
  • Twilio signature validation is implemented for inbound voice webhook paths in Hub router flow:
    • _validate_twilio_signature(...) in Aventora-Assistant/server/routers/inbound.py
  • Telnyx signature helper is imported and used for relevant paths:
    • verify_telnyx_webhook_signature in Aventora-Assistant/server/routers/inbound.py

domain-chatbot API​

  • Main API app with mounted routers:
    • domain-chatbot/LLM_full/main.py
  • Auth and token validation path:
    • domain-chatbot/LLM_full/auth/router.py
    • domain-chatbot/LLM_full/auth/service.py

domain-chatbot phone webhook​

  • Twilio signature validation in phone webhook handler:
    • domain-chatbot/Agent/phone/webhook.py

Authenticated Business Flows (Confirmed)​

API key based access (Hub)​

  • API key auth + permission checks are dependency-driven:
    • Aventora-Assistant/auth/middleware.py
  • API keys are hash-stored and permissioned:
    • Aventora-Assistant/db/api_key_manager.py

JWT + domain API key model (domain-chatbot)​

  • JWT issuance/refresh/validate and domain API key auth implemented:
    • domain-chatbot/LLM_full/auth/router.py
    • domain-chatbot/LLM_full/auth/service.py

Service-to-service delegation​

  • Hub can validate JWT via domain-chatbot /auth/validate-token for hybrid admin flow:
    • Aventora-Assistant/auth/middleware.py

Sensitive Data Flow (Confirmed)​

  • OAuth access/refresh tokens saved in Hub users table paths:
    • Aventora-Assistant/db/user_manager.py
  • Domain chatbot API keys mapped per account in Hub accounts table:
    • Aventora-Assistant/db/account_manager.py
  • Domain API keys and temporary tokens in domain-chatbot tables:
    • domain-chatbot/LLM_full/db_operations.py

Data Egress (Confirmed)​

  • AI prompt/response traffic to OpenAI/Groq through service layers.
  • Telephony/SMS/WhatsApp payloads to Twilio/Telnyx.
  • Calendar and identity flows to Microsoft/Google OAuth endpoints.

Assumptions (Explicit)​

  • End-to-end TLS is assumed at transport boundaries but not proven for every ingress hop in repository code.
  • Network segmentation between components is infrastructure-dependent and not verifiable here.

Gaps / Risks​

  • Hub CORS policy allows wildcard origin in current server config (Aventora-Assistant/server/server.py).
  • Potential overexposure in logs due to request body/header previews in middleware and validation handlers:
    • Aventora-Assistant/server/middleware/timing.py
    • domain-chatbot/LLM_full/main.py
  • Some rate limiting is conditional and not uniformly applied across all authenticated routes:
    • domain-chatbot/LLM_full/utils/rate_limiter.py

Mermaid Data Flow​

sequenceDiagram
  participant U as User/Client
  participant H as Hub API
  participant D as Domain API
  participant A as Agent Runtime
  participant P as PostgreSQL
  participant X as External Providers

  U->>H: API request (API key/JWT)
  H->>H: Auth dependency checks
  H->>P: Read/write account, calls, sessions
  H->>D: Validate token / domain data fetch
  D->>P: Read/write users, domains, tokens
  H->>X: Twilio/OpenAI/OAuth/CRM calls

  Note over U,A: Telephony/stream channel
  U->>A: Voice or chat channel request
  A->>P: Read domain/user settings
  A->>X: LLM/STT/TTS/telephony APIs
  A-->>U: AI response / call actions

Boundary Control Recommendations​

  1. Standardize boundary controls with a single ingress policy baseline (origin allowlist, header hardening, body limits).
  2. Enforce consistent webhook signature validation on all webhook-capable routes.
  3. Add data classification tags for log/event pipelines to prevent sensitive payload leakage.