ArylLabsArylLabs/Docs
Docs›Page

ArylHive File Share Infrastructure

This core document provides an architectural breakdown of the File Share System within ArylHive. It details how users convert their underlying storage assets into securely shareable, gated links that handle millions of requests gracefully on the edge.

1. High-Level Architecture Overview

The File Share system utilizes a globally distributed Cloudflare Worker Edge combined with Turso (LibSQL) at the edge for sub-millisecond route resolution.

flowchart TB User((Visitor / End User)) CF_Edge["Cloudflare Edge Network\n(Worker)"] subgraph Databases Turso["Turso Shares DB\n(Routing & Metadata)"] D1["Cloudflare D1\n(Collected Emails)"] AE["Analytics Engine\n(View Tracking)"] end subgraph Storage R2["Cloudflare R2"] Drive["Google Drive API"] B2["Backblaze B2"] end User -- "Visits [id].aryl.cloud\nor Request Download" --> CF_Edge CF_Edge -- "1. Fast Lookup Route" --> Turso CF_Edge -- "2. Check Auth Gates (Password/Email)" -.-> D1 CF_Edge -- "3. Log Async View (Non-blocking)" -.-> AE CF_Edge -- "4. Stream File Content" --> R2 CF_Edge -- "4. Proxy File Content" --> Drive CF_Edge -- "4. Retrieve Asset" --> B2

2. Core Components

A. The Edge Router (Worker)

The Cloudflare Worker evaluates every incoming request to *.aryl.cloud:

  1. Subdomain Extraction: It strips the [id] from [id].aryl.cloud.
  2. Metadata Lookup: Queries the isolated Turso share_db for the routing metadata associated with that ID.
  3. Access Control: Evaluates whether the file requires authentication, a password, or lead capture (email gate).
  4. Proxying / Streaming: It creates a secure stream directly from the underlying file location (R2, B2, or Google Drive) directly to the end user without exposing original cloud URLs.

B. The Shares Database (Turso)

To ensure maximum speed, all share links belong to a dedicated Turso database isolated from the main application database.

  • id (Primary Key, nanoID) - e.g., 6p8r6k
  • user_id - The creator string reference
  • file_id / r2_path - The target asset pointer
  • provider - E.g., google-drive, r2, b2
  • visibility - public or private
  • password - Hashed password for gate
  • require_email - Boolean gate for Lead Capture
  • expires_at - Timestamp logic for Guest user cleanups

C. The Lead Capture System (D1)

If a share link is gated behind require_email, the Worker intercepts the request and returns a lightweight visual UI form instead of the file.

  1. Emails are validated natively via RFC regex and Disposable Email Domain blocklists.
  2. Verified via Cloudflare DNS-over-HTTPS for active MX records.
  3. Automatically written to a highly-available Cloudflare D1 SQLite database rather than Turso to lower operational write-costs.
  4. A secure, short-lived cookie is dropped on the visitor's browser granting access to the asset.

3. The Request Lifecycle (Visualized)

Here is the exact step-by-step sequence of what happens when a user clicks a shared link like https://try-now-6p8r6k.aryl.cloud.

sequenceDiagram participant User participant Worker as CF Worker Edge participant Turso as Turso (Shares DB) participant Auth as Access Gates (Password / D1 Email) participant Storage as File Storage (R2/Drive/B2) participant Analytics as CF Analytics Engine User->>Worker: GET https://[id].aryl.cloud/ %% Look up Record Worker->>Turso: SELECT * FROM shares WHERE subdomain = [id] Turso-->>Worker: Return Metadata & Configuration %% Access Control Loop alt Share has expired Worker-->>User: 410 Gone "Share Expired" else Visibility is Private Worker->>Worker: Check User JWT Session alt Unauthorized Worker-->>User: 403 HTML Private Gate end else Requires Password Worker->>Worker: Check share_pwd_[id] cookie alt No Cookie or Invalid Worker-->>User: 200 HTML Password Gate end else Requires Email (Lead Capture) Worker->>Worker: Check share_email_[id] cookie alt No Cookie Worker-->>User: 200 HTML Lead Capture Gate end end %% Async Tracking Worker--)Analytics: Fire-and-forget (Log 1 View) %% Fetch and Stream file Worker->>Storage: Fetch file content (Stream) Storage-->>Worker: Data Chunks Worker-->>User: 200 OK (Stream / Download / Render)

4. Advanced Technical Decisions

Cross-Origin / Domain Strategy

The platform separates raw website deployments (*.aryl.app) from shared files (*.aryl.cloud). Doing so prevents security vulnerabilities like cookie-stealing and XSS. If a user uploads a malicious HTML file and shares it via the platform, dropping it on .aryl.cloud prevents it from accessing the local context or cookies of their website deployments on .aryl.app.

Analytics Engine vs. Relational DB

File views are tracked using Cloudflare Analytics Engine rather than SQL UPDATE views = views + 1. Since a popular file share could get hit thousands of times a second, updating a relational database counter would cause extreme lock contention or API rate limits. Writing to Analytics Engine is non-blocking (fire-and-forget), immensely fast, and highly scalable. Periodically, the UI aggregates these raw edge events for the dashboard.

Next: Learn about The Edge Network →