CatBot Technical Architecture Specifications

Executive Summary

Pet health triage chatbot using freemium model with Anthropic LLM integration. Focus on ethical anxiety management through practical competence building.

System Architecture Overview

High-Level Architecture

[Frontend] → [API Gateway] → [Application Layer] → [LLM Service] → [Anthropic API]
     ↓              ↓               ↓                    ↓
[CDN/Media] → [Load Balancer] → [Database Layer] → [Cache Layer]

Technology Stack

• Frontend: React/Next.js with TypeScript
• Backend: Node.js with Express or Python with FastAPI
• Database: PostgreSQL (primary), Redis (cache/sessions)
• LLM Integration: Anthropic Claude API
• Media Storage: AWS S3 or Cloudflare R2
• Infrastructure: Docker containers on AWS/GCP
• Monitoring: DataDog, Sentry for error tracking

Data Architecture

Database Schema Design

Users Table

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    subscription_tier VARCHAR(50) DEFAULT 'free',
    subscription_expires_at TIMESTAMP,
    data_retention_consent BOOLEAN DEFAULT false,
    last_active TIMESTAMP
);

Cat Profiles Table

CREATE TABLE cat_profiles (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(100) NOT NULL,
    age_months INTEGER,
    breed VARCHAR(100),
    weight_kg DECIMAL(4,2),
    medical_history JSONB,
    current_medications JSONB,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

Conversations Table

CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    cat_id UUID REFERENCES cat_profiles(id),
    session_id VARCHAR(255),
    triage_outcome VARCHAR(50), -- emergency, urgent, routine, monitor
    symptoms_reported JSONB,
    recommendations_given JSONB,
    follow_up_scheduled TIMESTAMP,
    vet_visit_occurred BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT NOW(),
    expires_at TIMESTAMP -- for data retention
);

Messages Table

    CREATE TABLE messages (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE,
        role VARCHAR(20) NOT NULL, -- user, assistant, system
    content TEXT NOT NULL,
    metadata JSONB, -- tokens used, response time, etc.
    created_at TIMESTAMP DEFAULT NOW()
);

Media Attachments Table

CREATE TABLE media_attachments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE,
    message_id UUID REFERENCES messages(id),
    file_type VARCHAR(50), -- image, video
    file_url VARCHAR(500),
    file_size_bytes INTEGER,
    analysis_results JSONB, -- AI-generated descriptions
    created_at TIMESTAMP DEFAULT NOW()
);

Data Flow Architecture

Request Processing Flow

1. User Input → API Gateway (rate limiting, auth)
2. Session Management → Redis lookup/creation
3. Context Building → Fetch cat profile + conversation history
4. LLM Preparation → Structure prompt with context
5. Anthropic API Call → Send structured request
6. Response Processing → Parse, validate, store response
7. Client Response → Return formatted response + metadata

Data Retention Strategy

• Free Users: 48-hour conversation retention
• Premium Users: Full history retention with user control
• Media Files: 30-day retention (free), unlimited (premium)
• Analytics Data: Anonymized, indefinite retention

LLM Integration Architecture

Anthropic API Integration

Prompt Engineering Structure

SYSTEM_PROMPT_TEMPLATE = """
You are a professional pet health triage assistant specializing in cats.

CONTEXT:
Cat Profile: {cat_profile}
Medical History: {medical_history}
Current Conversation: {conversation_summary}

GUIDELINES:
1. Provide practical, actionable guidance
2. Clear urgency assessment (emergency/urgent/routine/monitor)
3. Suggest specific documentation to help veterinarians
4. Offer appropriate reassurance through competence building
5. Never provide definitive diagnosis - always recommend veterinary consultation

RESPONSE FORMAT:
- Urgency Level: [level]
- Immediate Actions: [numbered list]
- Documentation Suggestions: [what to observe/record]
- Veterinary Recommendation: [timing and type]
- Follow-up Guidance: [what to monitor]
"""

Conversation State Management

class ConversationContext:
    def __init__(self, conversation_id):
        self.conversation_id = conversation_id
        self.cat_profile = self.load_cat_profile()
        self.message_history = self.load_recent_messages()
        self.session_metadata = self.load_session_data()

    def build_prompt(self, user_message):
        context = {
            'cat_profile': self.cat_profile,
            'medical_history': self.get_relevant_history(),
            'conversation_summary': self.summarize_conversation(),
            'user_message': user_message
        }
        return SYSTEM_PROMPT_TEMPLATE.format(**context)

    def process_response(self, llm_response):
        # Parse structured response
        # Extract triage decision
        # Store recommendations
        # Update conversation state
        pass

Cost Optimization Strategies

Response Caching System

class ResponseCache:
    def __init__(self, redis_client):
        self.redis = redis_client
        self.cache_ttl = 3600  # 1 hour

    def get_cache_key(self, symptoms, cat_profile_hash):
        # Generate hash of symptoms + basic cat info
        return f"response:{hash(symptoms)}:{cat_profile_hash}"

    def should_cache_response(self, urgency_level):
        # Cache routine responses, not emergencies
        return urgency_level in ['routine', 'monitor']

Token Usage Optimization

• Conversation summarization after 10+ exchanges
• Context pruning for long conversations
• Batch processing for multiple questions
• Response streaming for better UX

Security & Privacy Architecture

Data Protection Measures

• Encryption at Rest: AES-256 for database
• Encryption in Transit: TLS 1.3 for all communications
• API Security: Rate limiting, JWT authentication
• Data Anonymization: Hash personal identifiers for analytics

Privacy Compliance

• Data Minimization: Collect only necessary information
• User Control: Data export, deletion on request
• Consent Management: Granular permissions for data use
• Audit Logging: Track data access and modifications

Error Handling & Fallbacks

class LLMService:
    async def get_triage_response(self, prompt, context):
        try:
            response = await self.anthropic_client.complete(prompt)
            return self.parse_structured_response(response)
        except AnthropicAPIError as e:
            if e.status_code == 429:  # Rate limit
                return self.get_cached_fallback(context)
            elif e.status_code >= 500:  # Server error
                return self.get_emergency_fallback()
            else:
                raise
        except Exception as e:
            logger.error(f"Unexpected error: {e}")
            return self.get_safe_fallback()

Monitoring & Analytics

Key Metrics to Track

• Usage Metrics: Sessions/day, messages/session, user retention
• Quality Metrics: Triage accuracy, user satisfaction scores
• Business Metrics: Conversion rate (free→premium), revenue per user
• Technical Metrics: API response times, error rates, cache hit rates

Logging Strategy

LOGGING_CONFIG = {
    'conversation_events': {
        'conversation_started',
        'triage_provided',
        'emergency_detected',
        'vet_referral_made',
        'follow_up_scheduled'
    },
    'business_events': {
        'user_upgraded',
        'subscription_renewed',
        'feature_accessed'
    },
    'technical_events': {
        'api_call_made',
        'cache_hit',
        'error_occurred'
    }
}

Deployment Architecture

Infrastructure Components

• Application Servers: Auto-scaling container groups
• Database: Primary/replica PostgreSQL setup
• Cache Layer: Redis cluster for session management
• CDN: Cloudflare for static assets and media
• Load Balancer: Application-level load balancing

CI/CD Pipeline

1. Code Commit → GitHub/GitLab
2. Automated Testing → Unit, integration, end-to-end tests
3. Security Scanning → Dependency vulnerabilities, secrets detection
4. Staging Deployment → Automated deployment to staging
5. Production Deployment → Manual approval + blue-green deployment

Backup & Disaster Recovery

• Database Backups: Daily automated backups with 30-day retention
• Media Backups: Cross-region replication
• Application Recovery: Infrastructure as code for rapid rebuilding
• Data Export: User data export functionality for compliance

Learning Resources & Implementation Guide

Core Technologies

• Node.js/Express: Express.js Documentation
• PostgreSQL: PostgreSQL Official Docs
• Redis: Redis Documentation
• Docker: Docker Getting Started

LLM Integration

• Anthropic API: Anthropic Documentation
• Prompt Engineering: Claude Prompt Engineering Guide
• LLM Best Practices: Research papers on conversational AI systems

Security & Compliance

• OWASP Security Guidelines: OWASP Top 10
• Data Privacy: GDPR compliance guides, privacy by design principles
• API Security: JWT implementation, rate limiting strategies

Business & Analytics

• SaaS Metrics: Cohort analysis, customer lifetime value calculation
• A/B Testing: Statistical significance testing, experiment design
• User Experience: Conversational interface design principles

Implementation Phases

Phase 1: MVP (4-6 weeks)

• Basic conversation interface
• Simple triage logic
• Free tier functionality
• Core database schema

Phase 2: Enhanced Features (6-8 weeks)

• Premium subscription system
• Advanced triage algorithms
• Media upload capability
• User profiles and cat management

Phase 3: Business Features (4-6 weeks)

• Vet referral system
• Analytics dashboard
• Automated follow-up system
• Advanced caching and optimization

Phase 4: Scale & Optimize (Ongoing)

• Performance optimization
• Advanced analytics
• A/B testing framework
• Additional monetization features

Risk Assessment & Mitigation

Technical Risks

• Anthropic API Limitations: Implement caching and fallback responses
• Scaling Challenges: Design for horizontal scaling from start
• Data Loss: Comprehensive backup and replication strategy

Business Risks

• Liability Concerns: Clear disclaimers, professional insurance
• Regulatory Changes: Monitor pet health app regulations
• Competition: Focus on unique value proposition and user experience

Operational Risks

• User Safety: Robust emergency detection and escalation
• Data Breaches: Security-first architecture and regular audits
• Service Reliability: High availability design and monitoring