Architecture

Architecture

Technical overview of Aletheia's system design.

---

System Overview

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

    subgraph CloudFlare
        B["CloudFlare Worker<br/>Rate Limit + DDoS"]
    end

    subgraph AWS
        C["Lambda Function URL"]
        D["Agent Lambda<br/>Python 3.12"]
        E["Auth Lambda<br/>Python 3.12"]
        F["Bedrock<br/>Anthropic Claude"]
        G[("DynamoDB<br/>4 Tables")]
        H["Secrets Manager"]
        I["CloudWatch<br/>EMF Metrics + X-Ray"]
    end

    subgraph External
        J["LinkedIn OAuth"]
        K["Stripe"]
    end

    A -->|"HTTPS + JWT"| B
    B -->|"Shared Secret"| C
    C --> D
    C --> E
    D --> F
    D -.-> G
    E -.-> G
    E -.-> H
    E -.-> J
    E -.-> K
    D -.-> I
    F -.->|"inference"| D

Loading

---

Components

Browser Extension

Component	Purpose
manifest.json	Extension configuration (Manifest V3)
service-worker.js	Background script handling events
content-safety.js	Client-side content filtering
overlay.js	UI rendering for analysis results
auth.js	LinkedIn OAuth flow, JWT management
popup.html/js	Login/logout UI, settings

Manifest versions:

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

Backend Services

Service	Technology	Purpose
Edge Proxy	CloudFlare Worker	Rate limiting, DDoS protection, shared secret injection
Agent Lambda	Lambda (Python 3.12)	Text analysis, AI orchestration
Auth Lambda	Lambda (Python 3.12)	OAuth, JWT issuance, billing, admin endpoints
AI	Bedrock (Anthropic Claude)	Etymology and context inference
State	DynamoDB (4 tables)	Agent state, users, token cap, coupons
Secrets	Secrets Manager	JWT signing key, LinkedIn OAuth, Stripe API keys
Observability	CloudWatch	EMF metrics, X-Ray tracing, structured logs
Billing	Stripe	Subscriptions, webhooks, checkout sessions

DynamoDB Tables

Table	Key Schema	Purpose
AletheiaAgentState	thread_id (PK), checkpoint_id (SK)	LangGraph state checkpoints
aletheia-users	user_id (PK)	User profiles, tier, Stripe IDs
aletheia-token-cap	PK, SK	Per-user rate limit counters
aletheia-coupons	code (PK)	Coupon codes for manual upgrades

GSIs:

• user_id-index on agent state table (GDPR data erasure)
• tier-index on users table (admin metrics queries)

TTL: Enabled on agent state (30 days), token cap (2h-35d by window), coupons (expiry attribute).

Security Layers

1. Client-side: Content safety checks before sending
2. Edge: CloudFlare DDoS protection + rate limiting (3 req/10s per IP)
3. Transport: Shared secret header (CloudFlare → Lambda)
4. Application: JWT validation with dual-secret rotation
5. Rate Limiting: Per-user multi-window caps (hourly/daily/monthly)
6. AI: Bedrock guardrails and prompt engineering
7. Cost Protection: CloudWatch alarm → kill switch, AWS Budget → IAM deny

---

Data Flow

Analysis Request Flow

1. User selects text and clicks "Explain with AI"
2. Extension performs client-side safety check
3. Request sent to api.aletheia.study with JWT Authorization: Bearer header
4. CloudFlare Worker validates rate limit, injects shared secret, forwards to Lambda
5. Agent Lambda validates shared secret header
6. @require_auth decorator validates JWT signature (cached secret, <1ms)
7. Multi-window rate limit check (DynamoDB TransactWriteItems)
8. Text sent to Bedrock (Anthropic Claude) for analysis
9. Response processed, EMF metrics emitted
10. Extension displays overlay with etymology analysis

Authentication Flow

1. User clicks "Sign In" in extension popup
2. Extension initiates LinkedIn OAuth flow
3. LinkedIn redirects to Auth Lambda callback with authorization code
4. Auth Lambda exchanges code for LinkedIn access token
5. Auth Lambda creates/updates user in DynamoDB
6. JWT issued (HS256, 24h expiry) with embedded tier and billing anchor day
7. Extension stores JWT, uses for subsequent API requests

Data Retention

• CloudWatch logs: 14-day retention (operational metrics only)
• User IDs: anonymized via SHA-256 truncation before logging
• Agent state: 30-day TTL auto-cleanup
• Rate limit counters: TTL cleanup (2h/2d/35d by window type)
• See Privacy Policy for complete details

---

Design Principles

ADR Highlights

ADR	Decision
10201	No <all_urls> permission
10204	Defense funnel (fail fast)
10211	Naked Python (no framework)
10216	CloudFlare replaces CloudFront+WAF
10217	JWT with HS256, Secrets Manager, dual-secret
10218	Multi-window rate limiting with DynamoDB
10219	Decorator-based auth middleware

Security Stance

• Defense in depth: 7 layers from edge to AI
• Minimal permissions: Only what's necessary
• Fail closed: Auth errors block rather than allow
• Privacy first: No tracking, anonymized logging, minimal data retention
• Cost protection: Budget alerts, concurrency limits, kill switches

---

Infrastructure

AWS Region

Primary deployment: us-east-1

Endpoints

Endpoint	Purpose
api.aletheia.study	Production API (via CloudFlare)
Agent Lambda Function URL	Direct access (shared secret required)
Auth Lambda Function URL	Direct access (shared secret required)

Monitoring

• CloudWatch EMF metrics: request counts by tier, cap denials, latency, Bedrock cost
• X-Ray tracing: end-to-end request debugging
• CloudWatch alarm: >100 invocations/5min triggers kill switch
• AWS Budget: auto-deny at 95% of $10/month

---

For Developers

See the Developer Guide for:

• Local development setup
• Testing procedures (975+ tests)
• Deployment instructions
• Contributing guidelines

---

Last updated: 2026-02-19