Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
218 lines (175 loc) · 8.13 KB

ARCHITECTURE.md

File metadata and controls

218 lines (175 loc) · 8.13 KB

Architecture: DojoCodingLabs Startups Android Marketplace

Vision

An F-Droid-compatible repository where startups incubated or accelerated through DojoCodingLabs hackathons and the DojoOS Launchpad can distribute their Android apps independently of Google Play.

Why This Exists

Immediate Value

  • Zero-cost distribution for startup apps
  • No Google Play Console account needed ($25 + identity verification)
  • No review queue — maintainer-approved, published in minutes
  • Community-driven quality through transparent scanning

Strategic Value (September 2026)

Google's Android Developer Verification Program will require all developers to register centrally with Google, submit government ID, and upload signing keys. Apps from unregistered developers will be blocked. This marketplace provides an alternative distribution channel. See KEEP_ANDROID_OPEN.md.

Core Design Principle

Developers publish on their own repos. We fetch from there.

Unlike a traditional app store where developers upload artifacts, this marketplace works like IzzyOnDroid:

  • Startups publish signed APKs as GitHub/GitLab/Codeberg releases
  • Our metadata points to the startup's release URL
  • Our pipeline fetches, scans, and indexes the APK
  • The startup never touches this repo directly

This means:

  • Developers control their own release cadence
  • No need to learn fdroidserver or F-Droid metadata format
  • Updates are detected automatically
  • APKs are always the official developer-signed build

Architecture

Startup's own repo (GitHub Releases)
         │
         │ Maintainer adds metadata
         ▼ pointing to startup's repo
┌─────────────────────────────┐
│  metadata/                   │
│  com.startup.app.yml         │  ← This repo
│    SourceCode: github.com/…  │
│    UpdateCheckMode: Tags     │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  update-and-deploy.yml       │  ← GitHub Actions (scheduled + on push)
│  1. fdroid checkupdates      │     Checks all metadata for new releases
│  2. Fetch new APKs           │     Downloads from startup's repo
│  3. apksigner verify         │     Validates signature
│  4. exodus-standalone scan   │     Tracker detection (informational)
│  5. fdroid update            │     Regenerates signed index
│  6. Deploy to Vercel         │     Static files to CDN
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  Vercel CDN                  │
│  marketplace.dojocoding.io   │
│  repo/index-v2.json          │
│  repo/*.apk                  │
└──────────┬──────────────────┘
           │
           ▼
   User's F-Droid client
   (Droid-ify, Neo Store)

Repository Structure

startups-android-marketplace/
├── .github/
│   ├── workflows/
│   │   ├── update-and-deploy.yml    # Fetch APKs + rebuild index + deploy
│   │   └── validate-metadata.yml    # Lint metadata YAML on PR
│   ├── ISSUE_TEMPLATE/
│   │   └── app-submission.yml       # Issue template for new submissions
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/
│   ├── ARCHITECTURE.md              # This file
│   ├── KEEP_ANDROID_OPEN.md         # Impact assessment + resilience plan
│   └── SUBMISSION_GUIDE.md          # Guide for maintainers adding apps
├── metadata/                        # One YAML file per app
│   └── com.startup.appname.yml
├── config.yml                       # fdroidserver configuration
├── vercel.json                      # Hosting config with security headers
├── .gitignore                       # Excludes repo/, keystores
├── LICENSE
└── README.md

What is NOT in this repo:

  • APK files (fetched at build time from developer repos)
  • The repo/ directory (generated by fdroidserver, deployed to Vercel)
  • Signing keystores (stored as GitHub Actions secrets)

Metadata Format

Each app has one YAML file in metadata/. This is managed by maintainers, not developers.

# metadata/com.startup.appname.yml
Categories:
  - Utilities
License: MIT
AuthorName: Startup Name
AuthorEmail: dev@startup.com
SourceCode: https://github.com/startup/app
IssueTracker: https://github.com/startup/app/issues

AutoName: App Name
Description: |
  Brief description of what the app does.

RepoType: git
Repo: https://github.com/startup/app.git

# How to detect new versions
UpdateCheckMode: Tags
AutoUpdateMode: Version

# DojoCodingLabs-specific fields
X-DojoLaunchpad: true
X-DojoHackathon: "Hackathon 2026-Q1"
X-DojoToolkit: flutter-go-to-market-toolkit

CurrentVersion: 1.0.0
CurrentVersionCode: 1

Key fields:

  • RepoType: git + Repo: — tells fdroidserver where to find releases
  • UpdateCheckMode: Tags — detect new versions from git tags
  • AutoUpdateMode: Version — auto-update metadata when new tags appear

Hosting: Vercel

Following the same deployment pattern as DojoOS:

  • Vercel serves the generated repo/ directory globally via CDN
  • Security headers (HSTS, X-Content-Type-Options, X-Frame-Options)
  • APK caching — immutable 1-year cache for versioned APK files
  • Index caching — 5-minute TTL (clients check for updates frequently)
  • Custom domain — marketplace.dojocoding.io

Update Pipeline

The pipeline runs on two triggers:

  1. Scheduled (e.g., daily) — checks all app repos for new releases
  2. On push to main — when a maintainer adds/modifies metadata
Schedule (daily) or push to main
  → fdroid checkupdates (checks all repos for new tags)
  → If new version found: download APK from developer's release
  → apksigner verify (reject if signature invalid)
  → exodus-standalone scan (informational, logged)
  → fdroid update (regenerate signed index with new APKs)
  → Deploy repo/ to Vercel

Security Model

Repository Signing

  • The repo index is signed with a keystore owned by DojoCodingLabs
  • Stored as FDROID_KEYSTORE_BASE64 in GitHub Actions secrets
  • Clients verify the signature before trusting the index
  • Key rotation requires all users to re-add the repo

APK Integrity

  • APKs are fetched directly from the developer's official releases
  • We verify the APK is properly signed (apksigner verify)
  • We do NOT re-sign APKs — the developer's signature is preserved
  • Updates must be signed with the same key as the original

Tracker Transparency

  • exodus-standalone scans detect known tracking SDKs
  • Results are informational — displayed in metadata, not blocking
  • Startups decide their own privacy posture

Onboarding Flow

For Startups (the app developer)

  1. Publish signed APK as a GitHub Release on their own repo
  2. Open an issue on this repo with the app submission template
  3. Done — maintainer handles the rest

For Maintainers (DojoCodingLabs team)

  1. Verify the startup's connection to a DojoCodingLabs program
  2. Create metadata/<package-name>.yml with correct repo URL
  3. Set UpdateCheckMode: Tags so future versions are auto-detected
  4. Push to main — pipeline fetches, scans, indexes, deploys
  5. Reply to the issue confirming the app is live

See SUBMISSION_GUIDE.md for the detailed maintainer workflow.

Future Enhancements

Phase 2: Reproducible Builds

  • Verify that APKs match source code using rbtlog
  • Display verification badges in the index

Phase 3: Web Portal

  • Landing page with app catalog (Material for MkDocs)
  • Search/filter by category, hackathon, toolkit usage
  • Download statistics

Phase 4: Automated Onboarding

  • Bot that watches for new issues with the submission template
  • Auto-generates metadata YAML from the issue fields
  • Opens a PR for maintainer review
  • Reduces maintainer effort to a single approval click