📺 AetherTime

The ultimate autonomous anime tracking ecosystem.

Note: This is a portfolio version of the AetherTime mono-repo. Production infrastructure, active secrets, and deployment bindings have been intentionally removed.

⚡ Project Overview

AetherTime is a complete autonomous media-tracking infrastructure designed to solve the fragmentation of the anime streaming ecosystem. Rather than relying on users to manually update their watch lists (MyAnimeList, AniList), AetherTime uses a sophisticated Chrome Extension paired with a highly scalable serverless backend to intelligently observe, map, and synchronize viewing habits across multiple disparate streaming platforms (Crunchyroll, Netflix, HiAnime, etc.) in real-time.

It features a Hybrid Runtime Architecture for capability inference, a Distributed Observer Fabric for cross-origin tracking, and a Serverless Cloudflare Worker backend heavily fortified with Cloudflare D1 (SQLite) for ACID canonical state resolution, AWS SQS for queue management, and AWS DynamoDB for raw telemetry evidence logging.

🖼️ Showcase

Dashboard Analytics	Continue Watching Queue

🚀 Feature List

• Hybrid Runtime Telemetry Engine: Automatically classifies streaming websites based on runtime capabilities rather than brittle hostname regexes.
• Cross-Origin Context Fabric: Safely maps state out of heavily isolated, nested CDN iframes using a cryptographically secure pub-sub bridge.
• Anime Authority & Telemetry Admission Engine: A bulk-processing pipeline that resolves identity evidence (Provider ID -> Canonical ATID), manages waitlists for missing metadata, and evaluates telemetry against canonical context.
• ACID/OCC Canonical Progression: Migrated user progression state entirely to Cloudflare D1 (SQLite) utilizing advanced ON CONFLICT and CASE WHEN SQL constraints to handle out-of-order deliveries, split-brain scenarios, and manual overrides without distributed locks.
• Event-Driven Resilience: Uses D1 Patrol Groups and AWS SQS Dead Letter Queues (DLQ) for massive shock absorption and out-of-band verification routing.

🏗️ Architecture Overview

The system is split into three primary planes: the Observation Plane (Extension), the Authority Plane (Telemetry Admission), and the Progression Plane (Canonical DB).

graph TD
    %% Observation Plane
    Browser[User Browser] -->|Observe| Ext[AetherTime Extension]
    Ext -->|POST /telemetry| API[Cloudflare Workers API]
    API -->|Batching| Patrol[(D1 Patrol Groups / Snapshots)]
    
    %% Authority Plane
    Patrol -->|Cron Worker| IntakeWorker[Anime Authority Intake Worker]
    IntakeWorker -->|Validates| AuthEngine[Telemetry Admission Engine]
    
    AuthEngine -->|1. PASS| CanonicalProcessingPipeline
    AuthEngine -->|2. VERIFY| SQS[(AWS SQS Verification Queue)]
    AuthEngine -->|3. IDENTITY_WAIT| Waitlist[Authority Waitlist Service]
    AuthEngine -->|4. REJECT| Unresolved[Unresolved Registry]

    %% Progression Plane
    CanonicalProcessingPipeline -->|Resolve Coordinates| Eval[Progression Application Service]
    
    Eval -->|1. Accumulate Watch Evidence| DDB[(AWS DynamoDB)]
    Eval -->|2. ACID Progression Mutate| Router[User Progress Write Router]
    Router -->|OCC & Source HWMs| D1[(Cloudflare D1 / SQLite)]
    
    D1 -->|Aggregates| Analytics[Analytics Pipeline]
    Analytics -->|Renders| React[React Dashboard]

(For a deep dive into the engineering decisions, read the Architecture Guide)

🛠️ Technology Stack

Frontend & Dashboard

• React 18 (Vite + TypeScript)
• TailwindCSS + Radix UI (shadcn)
• TanStack Query (Caching & state management)
• Zustand (External store for background synchronization)

Observation Engine (Chrome Extension)

• Manifest V3
• MutationObservers & History API for SPA awareness
• Secure postMessage Bridge for Cross-Origin Isolation bypass

Backend & Infrastructure

• Cloudflare Workers (V8 Isolate Edge compute)
• Cloudflare D1 / SQLite (Canonical progression, Patrol Groups, watch logs, ACID conflict resolution)
• AWS SQS (Exception handling & Out-of-band Verification Queues)
• AWS DynamoDB (Raw evidence aggregation, Single-Table Design)

🏁 Quick Start & Installation

Because this is a portfolio repository, you must supply your own infrastructure credentials to run the stack.

1. Environment Configuration

Create the required .env files using the template:

cp .env.example .env
cp .env.example backend/secrets/.env

Fill out the variables (AWS, Google, GitHub, etc.) as detailed in the .env.example.

2. Backend Setup

Deploy the Cloudflare Worker to your own account:

cd backend
npm install
# Set your secrets in Cloudflare
npx wrangler secret put AWS_ACCESS_KEY_ID
npx wrangler secret put AWS_SECRET_ACCESS_KEY
# Deploy
npm run deploy

3. Frontend Setup

Run the dashboard locally:

npm install
npm run dev

4. Extension Setup

1. Open Chrome and navigate to chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked and select the extension/ directory.

🔒 Security Notice

This repository has been sanitized for public release.

• All production API keys, AWS credentials, and OAuth secrets have been removed.
• The wrangler.toml has been scrubbed of production domains.
• If deploying, ensure you manage your own secrets via wrangler secret put and never commit your backend/secrets/.env file.

Please review SECURITY.md for vulnerability reporting and security constraints.

🧠 Engineering Highlights

This project was engineered to solve notoriously difficult problems in web observation and distributed systems:

1. The SPA Hydration Problem: Sites like Crunchyroll use Next.js routing, meaning the DOM never truly unloads. AetherTime uses an EnvironmentObserver to track virtual DOM mutations and History API pushes without causing memory leaks.
2. The Iframe Isolation Problem: Many Tier 2 streaming sites heavily utilize cross-origin iframes for video CDNs. We bypass this using a ContextFabric—a secure postMessage handshake that passes the Top Frame identity down to the isolated worker, ensuring accurate telemetry.
3. Resilient Event Idempotency & Split-Brain Resolution: The backend uses an asynchronous architecture through D1 Patrol Groups. To protect against split-brain scenarios and partial network partitions, canonical state mutations are resolved strictly within D1 via deterministic CASE WHEN SQL rules, utilizing ON CONFLICT constraints and source-specific high-water marks (e.g. tracked_progress vs manual_progress).

For more technical writeups, check out:

• Technical Decisions
• Telemetry Pipeline
• Data Model

🔮 Future Roadmap

• Dynamic Provider Registry: Migrate Tier 1 hardcoded arrays into a remote configuration system.
• Self-Healing Runtime: Introduce heuristics to automatically repair broken DOM selectors using machine learning.
• Composite Metadata Resolver: Merge overlapping fuzzy metadata with confidence decay.

Read the full Roadmap.

📄 License & Acknowledgements

This project is licensed under the MIT License.

Built with blood, sweat, and lots of caffeine. Designed for engineers who appreciate clean architectures, highly decoupled systems, and robust telemetry pipelines.