Ekaette Nova

AWS-native Ekaette backend using Amazon Nova on Bedrock.

Current State

• Backend runtime is AWS-only.
• Text, media, and WhatsApp voice-note understanding route through AWS services.
• Speech replies use Amazon Polly.
• Infrastructure is ECS/Fargate + ALB + ECR + DynamoDB + S3.
• The deployed ALB health endpoint is live.

Local Run

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

AWS Deployment

AWS infrastructure for the active stack lives under infra/aws/terraform.

Core flow:

terraform -chdir=infra/aws/terraform init
terraform -chdir=infra/aws/terraform plan -var-file=terraform.tfvars
terraform -chdir=infra/aws/terraform apply -var-file=terraform.tfvars

The current deployment uses:

• ACM certificate in us-east-1
• ALB in public subnets
• ECS Fargate service
• ECR image repository
• DynamoDB tables for runtime state
• S3 for media storage
• Secrets Manager for runtime secrets

Environment

Start from .env.example and set the Bedrock, WhatsApp, Africa's Talking, payment, and Transcribe values you actually use.

Important runtime values:

• LLM_PROVIDER=amazon_nova
• AWS_REGION=us-east-1
• NOVA_REASONING_MODEL_ID=us.amazon.nova-2-lite-v1:0
• NOVA_VISION_MODEL_ID=us.amazon.nova-pro-v1:0
• POLLY_VOICE_ID=Joanna
• S3_MEDIA_BUCKET=<bucket used for WhatsApp media + transcription>

Architecture

Mermaid source

graph TB
    subgraph "Client Layer"
        WEB["Web / Mobile Web"]
        PHONE["Phone Call"]
        WA_CALL["WhatsApp Call"]
        WA_MSG["WhatsApp Chat"]
    end

    subgraph "Channel Providers"
        AT_HTTP["Africa's Talking<br/>Voice webhooks + XML control"]
        AT_SIP["Africa's Talking<br/>SIP registrar + RTP"]
        META["Meta WhatsApp<br/>Calls + webhooks"]
    end

    subgraph "ECS Fargate — API Service"
        CTRL["Public + Channel APIs<br/>AT voice callback, WhatsApp webhook,<br/>SMS, uploads"]
        TEXT["Text Runtime<br/>WhatsApp / SMS messages<br/>(Nova 2 Lite)"]
    end

    subgraph "EC2 — SIP Bridge VM"
        SIP_B["AT + WhatsApp SIP bridge<br/>Opus codec, SRTP encryption,<br/>Polly TTS greeting, turn detection"]
        subgraph "Nova Sonic Voice Session"
            SONIC["Amazon Nova 2 Sonic<br/>Bidirectional voice streaming"]
            PROMPT["Prompt Builder<br/>Company knowledge + product catalog<br/>Nigerian English persona"]
        end
    end

    subgraph "AWS Services"
        BEDROCK["Amazon Bedrock"]
        POLLY["Amazon Polly<br/>TTS greeting synthesis"]
        S3["S3<br/>Media storage"]
        DYNAMO["DynamoDB<br/>Sessions + registry"]
        SECRETS["Secrets Manager"]
        SSM["Systems Manager<br/>Deployment"]
    end

    subgraph "AI Models (Bedrock)"
        NOVA_SONIC["Nova 2 Sonic<br/>Realtime voice"]
        NOVA_LITE["Nova 2 Lite<br/>Text reasoning"]
    end

    WEB -->|"HTTP"| CTRL
    PHONE -->|"PSTN"| AT_HTTP
    AT_HTTP -->|"POST /api/v1/at/voice/callback"| CTRL
    CTRL -->|"Dial XML (sip:...)"| AT_HTTP
    AT_HTTP -->|"SIP INVITE / RTP"| AT_SIP
    AT_SIP --> SIP_B
    WA_CALL -->|"WhatsApp calling"| META
    META --> SIP_B
    WA_MSG -->|"Webhook / send"| META
    META --> CTRL

    SIP_B -->|"Opus/SRTP"| SONIC
    PROMPT --> SONIC
    SONIC -.->|"Bidi Audio Stream"| NOVA_SONIC
    SIP_B -.->|"TTS"| POLLY
    CTRL --> TEXT
    TEXT -.->|"Converse API"| NOVA_LITE
    SONIC --> S3
    CTRL --> DYNAMO
    SIP_B --> SECRETS
    SSM --> SIP_B
    NOVA_SONIC --> BEDROCK
    NOVA_LITE --> BEDROCK

Loading

Deployment architecture: Ekaette Nova uses a split AWS architecture. The ECS Fargate service handles HTTP APIs, webhooks, AT XML call control, and text channels (WhatsApp/SMS). The EC2 SIP bridge VM handles real-time voice — Africa's Talking and WhatsApp media conversion, Opus/SRTP encryption, Polly TTS greeting, and bidirectional Nova Sonic voice streaming. Company knowledge (policies, products, prices) is embedded in the system prompt via vendored JSON, grounding the agent in Nigerian English with accurate catalog data.

Notes

• Africa's Talking and Meta remain the channel providers. AWS replaces the former Google/Gemini runtime and hosting layers.
• The old Google/Gemini backend, admin, realtime, and SIP bridge codepaths have been removed from the active repo surface.
• The main remaining migration area is the frontend live-call path, which still needs a dedicated AWS/Nova rewrite.