Archety Testing Dashboard Documentation¶

Last Updated: November 18, 2025 Status: ✅ Production-Grade Testing Interface

Overview¶

The Archety Testing Dashboard is a professional-grade testing interface for your iMessage AI assistant backend. It provides both a production-quality web UI (Stripe/Ramp/Brex inspired) and CLI interface for comprehensive backend testing.

Purpose¶

Professional Testing Dashboard: Production-quality SaaS interface styled after Stripe/Ramp/Brex
Chat with Sage: Test real conversations with your AI assistant in real-time
Fast Iteration: Test conversations and features without physical device
Automated Testing: CLI enables test scripts and CI/CD integration
No Telegram Needed: Direct backend testing without third-party services

Architecture¶

Test App Components:
├── CLI (./test-cli)          - Command-line interface for scripting
├── Web UI (./test-web)       - Streamlit visual interface
├── Helper Script (./test.sh) - Quick testing shortcuts
└── Core Libraries
    ├── api_client.py         - Backend communication
    ├── user_manager.py       - Test user management
    ├── message_builder.py    - Message construction
    └── image_handler.py      - Image encoding/handling

Installation¶

# Install test dependencies
pip install -r requirements-test.txt

# Dependencies installed:
# - requests (API calls)
# - streamlit (Web UI)
# - Pillow (image handling)

Configuration¶

Environment Variables¶

# Required
export RELAY_WEBHOOK_SECRET="<REDACTED_HEX_SECRET>"

# Optional
export API_BASE_URL="https://archety-backend-dev.up.railway.app"  # Defaults to dev
export TEST_ENV="dev"  # dev, staging, production

Authentication¶

Secret: Uses same RELAY_WEBHOOK_SECRET as Mac mini edge client
Identity: Sends relay_id="test-app" to distinguish from real relays
Future: Other relays will use relay_id="mac-mini-dev", relay_id="mac-mini-prod", etc.

Quick Start¶

Helper Script (Recommended)¶

# Test backend connection
./test.sh heartbeat

# Send a message
./test.sh send "Hello Sage!"

# Launch Web UI
./test.sh web

# Use CLI directly
./test.sh cli list-users
./test.sh cli scenario bill-split

CLI Usage¶

# Check connection
./test-cli --api-url https://archety-backend-dev.up.railway.app heartbeat

# List test users
./test-cli list-users

# Send direct message
./test-cli send "+15551234567" "+15559876543" "Hey, how are you?"

# Create test user
./test-cli create-user "+15551111111" "David Test" --email david@test.com

# Run scenario
./test-cli scenario bill-split

Web UI Usage¶

# Launch professional testing dashboard
./test.sh web

# Or with streamlit directly
streamlit run test_app/web/app.py

Then open http://localhost:8501 in your browser.

Features: - Professional Design: Stripe/Ramp/Brex-inspired interface - Chat Interface: Real-time conversation with Sage - Quick Tests: Pre-built test scenarios (greetings, calendar, email, emotional support) - Session Metrics: Message count, average response time tracking - Backend Status: Real-time connection monitoring - API Inspector: View request payloads and responses

Test Users¶

Default test users (created automatically):

Name	Phone	Email
Alice Test	+15551234567	alice@test.com
Bob Test	+15559876543	bob@test.com
Charlie Test	+15555555555	charlie@test.com

API Integration¶

Endpoint Used¶

Current: POST /edge/message - Purpose: Edge client message simulation (Mac mini + test app) - Schema: FilteredMessage - Authentication: Bearer token (EDGE_SECRET) - Messaging: All messages route to Sage (your AI assistant)

Payload Format¶

{
  "thread_id": "iMessage;-;+15551234567",
  "sender": "+15551234567",
  "filtered_text": "Hey Sage, how are you?",
  "original_timestamp": "2025-11-18T12:00:00Z",
  "is_group": false,
  "participants": ["+15551234567"],
  "was_redacted": false,
  "redacted_fields": [],
  "filter_reason": "test_app_message"
}

Response Format¶

{
  "should_respond": true,
  "reply_bubbles": [
    "aww hiiii so good rn haha",
    "you? wanna vent or vibe?"
  ],
  "schedule_message": null
}

Pre-built Scenarios¶

Bill Splitting¶

Tests bill splitting mini-app in group chat.

./test-cli scenario bill-split

Tests new user onboarding flow.

./test-cli scenario new-user

Group Conversation¶

Tests group chat with polls and checklists.

./test-cli scenario group-conversation

Testing Checklist¶

Core Messaging¶

✅ Direct message sending and receiving
✅ Group chat with multiple participants
✅ Multi-bubble responses
✅ Message ordering and timestamps

Context & Memory¶

✅ Conversation context retention
✅ User preferences and memories
✅ Relationship stage tracking

Special Features¶

✅ Image upload and sending
✅ Polls creation
✅ Checklists
✅ Bill splitting mini-app

Troubleshooting¶

Connection Refused¶

# Check backend is running
./test.sh heartbeat

# Try different environment
export API_BASE_URL="https://archety-backend-prod.up.railway.app"
./test.sh heartbeat

Unauthorized (401)¶

# Check webhook secret is set
echo $RELAY_WEBHOOK_SECRET

# Should output: <REDACTED_HEX_SECRET>

422 Validation Error¶

Ensure timestamp is int, not float
Check all required fields are present
Verify payload matches OrchestratorRequest schema

Development¶

Adding New Scenarios¶

Create file in test_app/scenarios/:

# test_app/scenarios/my_scenario.py

def run_my_scenario(**kwargs):
    """My custom test scenario"""
    from test_app.core import MessageBuilder, UserManager

    builder = MessageBuilder()
    manager = UserManager()

    # Scenario logic here

    return {"status": "success", "data": {...}}

Register in test_app/scenarios/__init__.py:

from .my_scenario import run_my_scenario

SCENARIOS = {
    "my-scenario": run_my_scenario,
    # ... other scenarios
}

Files Changed (Integration)¶

New Files¶

test_app/ - Full test app directory
test-cli - CLI launcher script
test-web - Web UI launcher script
test.sh - Helper script
requirements-test.txt - Test dependencies
QUICKSTART_TEST_APP.md - Quick start guide
IMESSAGE_RELAY_TECHNICAL_OVERVIEW.md - Technical details

Modified Files¶

test_app/core/api_client.py - Fixed timestamp type and payload schema
test_app/cli/main.py - Fixed bubble display handling

Redesign Notes (November 18, 2025)¶

Professional Dashboard Upgrade¶

The testing interface was completely redesigned to production SaaS quality:

Design Principles: - Stripe/Ramp/Brex Aesthetic: Clean, modern, minimalist professional design - User-Centric: Focus on "Chat with Sage" instead of user-to-user messaging - Production-Ready: Real metrics, status monitoring, request inspection

Key Improvements: 1. UI/UX Overhaul: - Custom CSS matching production SaaS standards - Professional color palette (#0066FF primary, #fafafa backgrounds) - Clean message bubbles with timestamps - Responsive layout with sidebar configuration

Messaging Clarity:
All messages now explicitly "to Sage"
Chat interface shows "You" → "Sage" conversation
Quick test buttons for common scenarios
Multi-bubble response display
Backend Integration:
Updated to /edge/message endpoint
FilteredMessage schema (not OrchestratorRequest)
EDGE_SECRET authentication (not RELAY_WEBHOOK_SECRET)
Proper timestamp formatting (ISO 8601)
Session Metrics:
Real-time message counter
Average response time tracking
Backend connection status
API payload inspector
Developer Experience:
Environment selector (Dev/Staging/Production)
Configurable API base URL
Clear conversation history management
Request/response debugging

Changelog¶

November 18, 2025 - Major Redesign¶

✅ Complete UI redesign to production SaaS quality (Stripe/Ramp/Brex inspired)
✅ Updated to /edge/message endpoint with FilteredMessage schema
✅ Chat with Sage interface - clarified all messages go to AI assistant
✅ Session metrics tracking - message count, response times
✅ Professional design system - custom CSS, clean layouts, modern aesthetics
✅ Quick test scenarios - pre-built buttons for common test cases
✅ API inspector - view request payloads and responses
✅ Fixed 422 validation error (timestamp int conversion)
✅ Fixed CLI bubble display (handle string/dict formats)
✅ Added test.sh helper script
✅ Configured proper authentication with EDGE_SECRET
✅ Updated CLI help text to clarify messaging to Sage

November 17, 2025¶

Initial creation of test app branch
Built CLI and Web UI interfaces
Created pre-built test scenarios