12 — Registry

The registry is where developers publish apps, models, components, and tools, and where users discover them.

Three registry types

Registry	Holds	Schema
App registry	Locara apps	manifest + signed binary + provenance
Model registry	Locara-curated model manifests	see 09-models.md
Tool registry	Locara-curated wasm tools	see 10-tools.md
Component registry	UI component source bundles	see 11-components.md

All four follow the same pattern: a structured manifest stored in a Git repo + signed artifacts on a CDN + a frontend that browses them.

Architecture

┌────────────────────────────────────────────────────────┐
│ Public Frontend (locara.app)                           │
│  ─ Cloudflare Pages (static)                           │
│  ─ Catalog browse, search, app pages                   │
└────────────────────────────────────────────────────────┘
              ▲                              │
              │                              ▼
┌────────────────────────────────────────────────────────┐
│ Registry API                                           │
│  ─ Read: signed manifests, search, ratings            │
│  ─ Write: GitHub Actions (publish) only               │
│  ─ Auth: GitHub OAuth + DNS verification              │
└────────────────────────────────────────────────────────┘
              ▲                              │
              │                              ▼
┌────────────────────────────────────────────────────────┐
│ Storage                                                │
│  ─ Postgres (manifest metadata, ratings, identities)   │
│  ─ R2 (signed artifacts, models, tool wasm)           │
│  ─ Sigstore log (provenance attestations)              │
└────────────────────────────────────────────────────────┘
              ▲
              │
┌────────────────────────────────────────────────────────┐
│ Review Pipeline (GitHub Actions)                       │
│  ─ Triggered on PR / submission                       │
│  ─ Builds artifact, runs static analysis               │
│  ─ Signs, generates provenance                         │
│  ─ Updates manifest DB                                 │
└────────────────────────────────────────────────────────┘

No always-on backend services beyond the static frontend + a thin API. Most logic runs in CI.

Submission flow (developer side)

1. Developer runs: locara publish
2. CLI verifies manifest, runs tests, packages source ref
3. CLI authenticates (publisher account, GitHub OAuth)
4. CLI pushes a "submission" record to registry: { repo_url, commit_sha, manifest, signature }
5. Registry triggers GitHub Action with the submission
6. Action clones the repo at the specified SHA, in a clean environment
7. Action runs:
   - locara verify --strict
   - locara test
   - locara build
   - Sigstore-style provenance attestation generation
   - Static analysis vs declared capabilities
8. Action uploads artifact to R2, manifest to Postgres
9. Manifest enters review queue (auto-approve low-risk; human for high-risk)
10. Once approved: app live on locara.app

The developer never uploads a binary. The developer’s machine being compromised cannot result in a compromised registry artifact. This is the npm-supply-chain lesson applied.

Auto-approve vs human review

Risk-based routing:

Risk class	Capabilities	Routing
Low	net=false, no device, no exec, no broad fs	Auto-approve in <10 min
Medium	net=allowlist OR device.mic/camera OR custom tools	Auto-approve if all checks pass; flag for spot review
High	net=true OR fs=broad OR exec.subprocess OR new publisher	Human review required

Auto-approve checks include:

• All static analysis warnings resolved.
• Provenance attestation valid.
• Sigstore log entry recorded.
• Manifest matches lockfile.
• No flagged content in display fields (description / screenshots).
• Publisher in good standing (no recent takedowns).
• Capability declarations consistent with prior versions of this app.

Failing any check moves the submission to human review.

Initially “human review” = the project lead. As volume grows, trusted reviewers from the community can be onboarded.

App registry record

Each published app version stored as:

{
  "publisher": "kingtongchoo",
  "name": "transcribe",
  "version": "0.1.0",
  "manifest": { ... },               // full locara.json
  "lockfile": { ... },               // resolved deps
  "artifact": {
    "url": "https://cdn.locara.app/apps/kingtongchoo/transcribe/0.1.0.tauri.zip",
    "sha256": "abc...",
    "size_bytes": 12345678
  },
  "provenance": {
    "build_url": "https://github.com/...",
    "commit_sha": "def...",
    "sigstore_log_id": "ghi..."
  },
  "review": {
    "status": "approved",
    "auto": true,
    "reviewed_at": "2026-04-30T10:00:00Z",
    "risk_class": "low"
  },
  "stats": {
    "installs": 0,
    "active_users_30d": 0,
    "ratings_count": 0,
    "ratings_avg": null
  },
  "published_at": "2026-04-30T10:00:00Z"
}

The frontend renders this into app pages.

Discovery surface

The frontend supports:

• Browse by category (Productivity, Creative, Developer Tools, etc.).
• Filter by capability (fully local, no microphone, etc.).
• Filter by device fit (will this run on my Mac? browser-side detection or manual filter).
• Search (full-text over name, description, tags).
• Featured collections (curated lists, e.g., “Best apps for journalists”).
• Reviews + ratings (per app, public).
• New / trending / recently updated (algorithmic surfaces with transparent ranking).

Ranking algorithm is publicly documented (Steam’s opacity is the cautionary tale).

App pages

Each app has a dedicated page at locara.app/<publisher>/<name>:

• Hero: name, tagline, screenshots, install button.
• Capability summary: “This app can: read user-selected files, transcribe audio. This app cannot: access network, use camera.”
• Privacy badges: ✓ fully local, ✓ no telemetry, ✓ open source.
• Device fit: “Requires 16 GB RAM, ~4 GB disk.”
• Models used: list with sizes + licenses.
• Tools used: list with capabilities each requires.
• Long description (markdown).
• Screenshots / video.
• Reviews and ratings.
• Source repo link.
• Publisher info.
• Version history with changelogs.

Capability summary is auto-generated from manifest — not author-written marketing.

Reviews & ratings

• Authenticated via a lightweight website account (GitHub OAuth) — required only to leave reviews / ratings, not to install or browse.
• Public, weighted by recency + helpfulness votes.
• Authors can respond.
• No deletion of ratings without admin involvement.
• Spam detection via rate limits + duplicate-content checks.

(open) Are reviews tied to verified installs? Pro: less spam. Con: more friction. Probably yes — only users with verifiable install of an app version can review it.

Verified publishers

Publisher accounts:

• Sign up via GitHub OAuth (defaults to GitHub identity).
• Verify control of a domain via DNS TXT record (optional but unlocks the “verified” badge).
• Set up Locara CI signing key (managed via GitHub Secrets).
• Set 2FA mandatory.

Verification levels:

Level	How	What it shows
Anonymous	Locara account only	Name shown; no badge
GitHub-verified	GitHub OAuth	GitHub username displayed
Domain-verified	DNS TXT	Domain name shown next to publisher
Locara-vetted	Manual review (rare)	“Trusted publisher” badge

Higher verification = higher trust score = preferred placement in some surfaces (e.g., featured).

Multi-registry / federation

Because Locara has no proprietary client app, “multi-registry” simply means multiple websites can serve catalogs of Locara-built apps.

• The official catalog is locara.app (curated by the Locara project).
• Anyone can run a competing or supplementary catalog at apps.acme-internal.com, listing apps relevant to their audience.
• An enterprise running a private catalog hosts the same kind of static site that lists internal .dmg artifacts.
• Each Locara app downloaded from any catalog is a normal Mac app — the trust mechanics travel with the artifact.

User experience: the user just downloads .dmg files from whichever website they trust. No client-side configuration of “registries”; the user’s choice of website is the choice.

For trust:

• The official Locara registry signs with Locara’s Apple Developer ID.
• A third-party catalog hosting Locara-built apps still benefits from Locara’s signing if those apps came through Locara CI.
• A third-party catalog hosting its own apps would need to sign them itself — those apps wouldn’t carry Locara’s signing chain unless they went through Locara CI.

Open data

The official registry’s data is publicly available:

• Manifest entries: indexable, downloadable as JSON.
• Provenance log: Sigstore-public, auditable.
• Review history: timestamped, sourced.
• Ranking algorithm: published code, reproducible.

This transparency is part of the trust pitch. Anyone can mirror, audit, or fork the registry.

Operational scale (phase 3)

Through phase 3 (10–100 apps, 1000s of users):

Component	Service	Cost/mo
Frontend	Cloudflare Pages	$0
API	Cloudflare Workers (or Vercel Functions)	$0–10
DB	Neon Postgres free tier	$0
Artifact CDN	Cloudflare R2	$0–30
Provenance log	Sigstore public good	$0
GitHub Actions	Public repo	$0
Domain	locara.app	$30/yr
Apple Dev Program	(for app signing)	$99/yr

Total <$50/mo. No always-on backend that needs babysitting.

At >10k MAU, Postgres tier may need upgrade; R2 egress may scale; CDN may need optimization. Phase 4+ problems.

Cross-references

• Trust mechanics + signing: 14-trust-safety.md
• Distribution / install flow on user side: 15-distribution.md
• Build pipeline / CI: 16-build.md
• App / model / tool / component manifest formats: 02-manifest.md, 09-models.md, 10-tools.md, 11-components.md
• Marketplace research: Apple App Store, Steam, Shopify App Store, npm