The Engineering "Magic"

Architecture & Workarounds for a $0 Budget

Note: Orion's architecture is built on a single constraint: $0 Budget. This constraint forced us to invent novel ways to use existing infrastructure (GitHub) as a high-performance CDN and Database.

A. The "Ghost Branch" Protocol

The Bloat Problem

In a traditional Git workflow, "History" is a feature. However, for a high-frequency database, history is technical debt. If Orion were to commit updates for 10,000 apps every 6 hours using standard Git practices, the .git folder—which users must verify—would grow exponentially. Within months, users would be downloading Gigabytes of useless commit history just to get the current state of the store.

The Orphan Solution

We solved this by treating the data branch not as a version control log, but as an ephemeral Snapshot State. The core innovation is the use of "Orphan Branches"—branches that share no commit history with the main tree.

Every 6 hours, our automation runner checks out a completely new, empty orphan branch. It constructs the entire database state from scratch in memory, writes it to the file system, and commits it as the first and only commit. It then force-pushes this branch to origin/data. To the Git object model, the "history" never happened. The repository size remains constant (~500KB) regardless of how many years the store runs. 

graph TD
    A[Start: 6 Hour Timer] --> B[CI Runner Starts]
    B --> C{Orphan Branch?}
    C -->|Yes| D[Checkout --orphan temp]
    D --> E[Git Add -A]
    E --> F[Git Commit 'Snapshot']
    F --> G[Delete Old 'data' Branch]
    G --> H[Rename 'temp' to 'data']
    H --> I[Force Push to Origin]
    I --> J[End: Repo Size Reset]

B. The "Menu vs. Chef" Protocol

The "Thundering Herd" API Limit

GitHub's REST API is generous for developers but draconian for applications, allowing only 60 unauthenticated requests per hour IP address. A traditional app architecture where the client queries an API server (The Chef) for data would be instantly rate-limited if just 100 users opened the app simultaneously.

Static CDN Delivery

Orion inverts this model. We never let the Service Client speak to the "Chef" (The API). Instead, our bots pre-compute the entire state of the application into static JSON headers—The "Menu".

This mirror.json is deployed to GitHub Pages, which is backed by a global Content Delivery Network (Fastly). When a user opens Orion, they are essentially downloading a static text file. This operation is idempotent, cacheable by ISPs, and completely invisible to GitHub's API rate limiters. We effectively "launder" dynamic API data into static assets.

The Scale Math:
  • Traditional REST: 10,000 users * 1 request = 10,000 API calls (Instant Ban).
  • Orion Protocol: 10,000 users * 1 fetch = 1 HTTP GET (Cached). Zero API cost.

C. Hierarchical Sharding

The Inode Limit: File systems like ext4 or NTFS begin to suffer performance degradation when a single directory contains more than 10,000 files. Listing such a directory becomes an O(N) operation, slowing down both the build bots and the user's device.

To support a theoretical limit of millions of apps, we implemented a deterministic sharding algorithm based on the package name. An app ID like com.spotify.music is tokenized and nested:

data/mirrors/s/p/spotify.json

This structure guarantees that no single folder ever exceeds a few hundred items, ensuring O(1) Lookup Times even if the store grows to the size of the Google Play Store.