Architecture

Architecture

Technical overview of Aletheia's system design.

---

System Overview

flowchart TD
    subgraph Client
        A["Browser Extension"]
    end

    subgraph AWS
        B["CloudFront + WAF"]
        C["Lambda<br/>Python 3.12"]
        D["Bedrock<br/>Nova Micro"]
        E[("DynamoDB")]
    end

    A -->|"HTTPS request"| B
    B --> C
    C --> D
    C -.-> E
    D -.->|"inference result"| C
    C -.->|"response"| B
    B -.->|"HTTPS response"| A

Loading

---

Components

Browser Extension

Component	Purpose
manifest.json	Extension configuration
service-worker.js	Background script handling events
content-safety.js	Client-side content filtering
overlay.js	UI rendering for analysis results

Manifest versions:

• Chrome: Manifest V3 (extensions/chrome/)
• Firefox: Manifest V2 (extensions/firefox/)

Backend Services

Service	Technology	Purpose
API Gateway	CloudFront	Request routing, caching
Security	WAF	Rate limiting, DDoS protection
Compute	Lambda	Request processing
AI	Bedrock	Claude 3 Haiku inference
State	DynamoDB	Session management

Security Layers

1. Client-side: Content safety checks before sending
2. Network: CloudFront + WAF filtering
3. Application: Input validation, prompt engineering
4. AI: Guardrails and safety checks

---

Data Flow

Request Flow

1. User selects text and clicks "Explain with AI"
2. Extension performs client-side safety check
3. Text sent to CloudFront endpoint
4. WAF validates request
5. Lambda receives and validates input
6. Guardrails check text safety
7. Request sent to Bedrock (Nova Micro)
8. Response processed and returned
9. Extension displays overlay

Data Retention

• Selected text, context, and URL stored for analytics (≤30 days with user ID)
• User ID removed after ≤30 days (data anonymized)
• CloudWatch logs contain only operational metrics (no user content)
• See Privacy Policy for complete details

---

Design Principles

ADR Highlights

ADR	Decision
0201	No <all_urls> permission
0202	Minimal permission model
0203	No PII stored in DynamoDB
0205	Client-side content safety
0207	Amazon Nova models (Nova Micro)

Security Stance

• Defense in depth: Multiple validation layers
• Minimal permissions: Only what's necessary
• Fail closed: Errors block rather than allow
• Privacy first: No tracking, minimal data retention

---

Infrastructure

AWS Region

Primary deployment: us-east-1

Endpoints

Environment	Purpose
Production	Live user traffic
Staging	Pre-release testing

Monitoring

• CloudWatch Logs for operational visibility
• CloudWatch Metrics for performance tracking
• X-Ray tracing for request debugging

---

For Developers

See the Developer Guide for:

• Local development setup
• Testing procedures
• Deployment instructions
• Contributing guidelines

---

Last updated: 2026-01-06 10:28 CT