ARCHANGEL

The Intelligent Layer for Fire TV

ARCHANGEL is a Fire TV intelligence and discovery application that connects viewers, applications, developers, and device-level experience signals through one interface.

The project is being developed for the Amazon Developer Build, Ship, Shape — Fire TV track.

Core idea

ARCHANGEL is designed as an intelligence layer rather than a replacement for Fire TV system software.

App Discovery Intelligence — natural-language application discovery, ranking, alternatives, and missing-app requests.
App Request Network — converts missing-app requests into aggregated developer-demand signals.
AdLens — planned monetization/ad-experience intelligence; it will not claim system-wide ad-blocking privileges.
Pulse — planned Fire TV experience diagnostics.
Sideload Sentinel — local APK metadata and compatibility inspection, SHA-256 calculation, signer-certificate fingerprints, permission rationale, and a separate Android SDK apksigner verification workflow. It does not claim to scan for malware.
ARCHANGEL Concierge — the AI layer that interprets natural-language requests and connects them to the verified catalog.

Architecture

                         ┌─────────────────────────┐
                         │        FIRE TV          │
                         │   React Native TV UI    │
                         └────────────┬────────────┘
                                      │ HTTP/JSON
                                      ▼
                         ┌─────────────────────────┐
                         │      ARCHANGEL API      │
                         │       Express.js        │
                         ├─────────────────────────┤
                         │ Catalog / Discovery     │
                         │ AI Concierge            │
                         │ App Requests            │
                         │ Demand Aggregation      │
                         └───────┬─────────┬───────┘
                                 │         │
                    ┌────────────┘         └──────────────┐
                    ▼                                     ▼
          ┌───────────────────┐                 ┌──────────────────┐
          │ Catalog / Shared   │                 │ AI Providers     │
          │ AppProfile models  │                 │ Gemini / Bedrock │
          │ catalog.seed.json  │                 └──────────────────┘
          └───────────────────┘

Repository structure

archangel/
│
├── backend/
│   ├── server.js                 # Express API
│   ├── ai.js                     # AI provider selection
│   ├── providers/
│   │   ├── gemini.js             # Gemini/Gemma discovery
│   │   └── bedrock.js            # Amazon Bedrock discovery
│   ├── data/requests.json        # Local app-request persistence
│   └── .env.example
│
├── fire-os/
│   ├── src/
│   │   ├── App.tsx
│   │   ├── lib/api.ts            # API client
│   │   ├── components/           # TV-focused reusable UI
│   │   └── screens/              # Home, Discover, Requests, Pulse, etc.
│   ├── android/                  # Android/Fire TV build project
│   └── package.json
│
├── shared/
│   └── src/
│       ├── types.ts              # Shared TypeScript models
│       └── catalog.seed.json     # Curated verified demo catalog
│
├── docs/
│   ├── ARCHITECTURE.md
│   └── AMAZON_APPSTORE_API_FEATURE_REQUEST.md
│
├── package.json
├── LICENSE
└── README.md

App Discovery architecture

User request
    │
    ▼
Normalize input
    │
    ├── Direct catalog match ──► SPECIFIC_APP
    │                              │
    │                              ▼
    │                         Open app profile
    │
    └── No direct match
           │
           ▼
       AI intent analysis
           │
     ┌─────┼──────────┬───────────┐
     ▼     ▼          ▼           ▼
 CAPABILITY CONTENT MISSING_APP AMBIGUOUS
     │     │          │
     └─────┴──────────┴──────────────►
                  │
                  ▼
          Verified alternatives
                  │
                  ▼
        Request missing application

The AI is constrained by the catalog:

It cannot invent an application ID.
Exact matches are validated against Fire OS catalog records.
Alternatives are filtered against the catalog.
Generic phrases such as some movies or music are not converted into fake application names.
A named application absent from the current catalog becomes a MISSING_APP request.
AI confidence is constrained to the 0–1 range and displayed as a percentage.

Catalog architecture

ARCHANGEL deliberately separates catalog ingestion from discovery intelligence.

curated-verified-cache
        │
        ▼
catalog.seed.json
        │
        ▼
normalized AppProfile
        │
        ├── Search
        ├── AI discovery
        ├── Alternatives
        └── App requests

The current catalog is a small verified demo cache, not a claim of complete Amazon Appstore coverage.

The API exposes catalog metadata through GET /catalog/status.

If Amazon provides an authorized Appstore-wide application catalog API/feed in the future, it can be added as another ingestion provider while keeping the normalized AppProfile model and downstream discovery system intact.

ARCHANGEL does not scrape, reverse-engineer, or bypass private Amazon Appstore endpoints.

AI architecture

The backend supports two selectable providers.

Gemini / Gemma

AI_PROVIDER=gemini
GEMINI_MODEL=gemma-4-31b-it
GEMINI_FALLBACK_MODEL=gemma-4-26b-a4b-it

The primary model is attempted first. If it fails, the configured fallback model is attempted.

Amazon Bedrock

AI_PROVIDER=bedrock
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=amazon.nova-lite-v1:0
AWS_BEARER_TOKEN_BEDROCK=

Provider selection is isolated in backend/ai.js, so the Fire TV client does not need to know which AI provider is active.

Development environment

The current working development environment is Windows.

Required

Node.js 20+
npm
JDK 17
Android Studio
Android SDK / platform tools
Android TV emulator or a Fire TV device
Git

Amazon documents React Native support for Fire TV and Android Studio/Android TV emulator development.

Recommended Windows paths

D:\archangel
D:\gradle
D:\android-avd
D:\npm-cache

Optional cache configuration:

setx GRADLE_USER_HOME D:\gradle
setx ANDROID_AVD_HOME D:\android-avd
npm config set cache D:\npm-cache

Installation

git clone https://github.com/Barnona/archangel.git
cd archangel
npm install
cd fire-os
npm install
cd ..

Create the backend environment file:

Copy-Item backend\.env.example backend\.env

For Gemini/Gemma, add the API key to backend/.env.

Do not commit .env or API keys.

Running the backend

From the repository root:

npm run api

The API listens on http://localhost:4000 and binds to 0.0.0.0 for LAN development.

Running the Fire TV app

Start Metro in a separate terminal:

cd D:\archangel\fire-os
npm start

For the Android TV emulator, fire-os/src/config.ts uses http://10.0.2.2:4000 to reach the Windows host.

Start the emulator from Android Studio or:

emulator -avd Television_1080p
adb devices

Build the debug APK:

cd D:\archangel\fire-os\android
.\gradlew.bat app:assembleDebug

Install it:

adb install -r "D:\archangel\fire-os\android\app\build\outputs\apk\debug\app-debug.apk"

Launch it:

adb shell monkey -p com.archangelnative 1

Amazon documents ADB as a development/testing mechanism for installing and running Fire TV applications.

Physical Fire TV workflow

Start the backend.
Start Metro if using a development bundle.
Find the Windows PC LAN IP.
Change fire-os/src/config.ts from http://10.0.2.2:4000 to http://<WINDOWS-PC-LAN-IP>:4000.
Connect the Fire TV through ADB.
Verify with adb devices -l.
Build and install the debug APK.
Launch ARCHANGEL.

For production, replace the local HTTP endpoint with an authenticated HTTPS service.

Automated backend smoke tests

With the backend running in a separate terminal, run from the repository root:

npm --workspace backend run test:smoke

The smoke test performs read-only requests against the local API by default. To test a different running instance, set ARCHANGEL_API_URL to its base URL. It does not call AI inference or create app requests.

API testing workflow

With the backend running:

Health

curl http://localhost:4000/health

Catalog status

curl http://localhost:4000/catalog/status

AdLens evidence refresh

AdLens history is maintained by an explicit refresh lifecycle rather than by read requests.

The API performs a baseline refresh when the backend starts and then repeats it at the configured interval:

ADLENS_REFRESH_INTERVAL_MS=86400000

Manual development refresh:

curl.exe -X POST http://localhost:4000/adlens/refresh

The refresh response reports:

apps checked
snapshots added
unchanged apps
detected data-signal changes

The refresh operates on ARCHANGEL's curated verified catalog. It does not claim access to an Amazon-wide live Appstore catalog.

Standard discovery

curl "http://localhost:4000/apps/discover?q=movies"

AI discovery

curl -X POST http://localhost:4000/ai/app-discovery -H "Content-Type: application/json" -d '{"request":"I want to watch Netflix"}'

Expected:

Netflix → SPECIFIC_APP → exactMatch = netflix

Missing application test:

curl -X POST http://localhost:4000/ai/app-discovery -H "Content-Type: application/json" -d '{"request":"I want to watch Crunchyroll"}'

Expected: MISSING_APP followed by the request flow.

Generic request test:

curl -X POST http://localhost:4000/ai/app-discovery -H "Content-Type: application/json" -d '{"request":"I want to watch some movies"}'

Expected: CONTENT/CAPABILITY behavior with no fake application name.

App request

curl -X POST http://localhost:4000/requests -H "Content-Type: application/json" -d '{"appName":"Crunchyroll","note":"Requested through ARCHANGEL"}'

Demand aggregation

curl http://localhost:4000/requests/demand

End-to-end testing checklist

Backend

/health returns ok: true
Catalog status loads
Catalog search works
Category filtering works
AI status identifies the active provider
Specific application requests resolve correctly
Missing applications create request signals
Generic requests do not create fake app names
Alternatives exist only in the verified catalog

Fire TV UI

Build

Debug APK builds successfully
APK installs through ADB
App launches from the TV launcher
API connection works from the target environment
No secrets are included in the repository

Current module status

Module	Status
Fire TV / Android TV client	Implemented; emulator is the available validation target
Light/red TV UI and D-pad navigation	Implemented
Curated app catalog and standard search	Implemented; catalog is not exhaustive
AI App Discovery / Concierge	Implemented with catalog-grounded response normalization and provider fallback
Alternatives and missing-app detection	Implemented
Request Network and demand aggregation	Implemented
AdLens	Implemented; evidence transparency is limited to available curated/catalog signals
Pulse Diagnostics	Implemented; backend smoke checks have previously passed; rerun before submission
Sideload Sentinel	Implemented for local APK metadata, declared permissions, hashing and signature-verification workflow; not a malware scanner; final emulator regression should be confirmed
Amazon Bedrock provider	Configured, but live inference is blocked by AWS account verification/activation; do not claim it was live-tested
Vega OS client	Not implemented; current target is the Android/Fire TV-compatible client

Design boundaries

ARCHANGEL is an application-layer intelligence system. It does not currently claim privileged control over Fire TV system processes, system-owned remote buttons, protected system state, system-wide advertising controls, unauthorized APK installation, or security/Appstore restrictions.

Diagnostics and ad intelligence will therefore be implemented around capabilities legitimately available to an application.

Roadmap

                    ARCHANGEL
                        │
             ┌──────────┴──────────┐
             │                     │
        CONCIERGE AI          FIRE TV INTELLIGENCE
             │                     │
      ┌──────┼──────┐       ┌──────┼────────┐
      │      │      │       │      │        │
   DISCOVER ADLENS REQUEST  PULSE SIDELOAD
      │      │      │       │      │        │
      ▼      ▼      ▼       ▼      ▼        ▼
    Apps    Ads   Demand   Health  APK   Compatibility

License

ARCHANGEL is released under the MIT License. See LICENSE.

The MIT license permits use, modification, distribution, and private/commercial use subject to its conditions, including preservation of the copyright notice.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.idea		.idea
backend		backend
docs		docs
fire-os		fire-os
scripts		scripts
shared		shared
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation