spaceforge / SPEC.md
2Btainment's picture
feat(android): bake SDK in Docker; return debug APK from download (zip fallback)
dbc2744 verified
|
Raw History Blame Contribute Delete
3.32 kB

SpaceForge β€” Architecture Spec (MVP)

Goal

Paste a Hugging Face Space URL β†’ analyze runtime/SDK β†’ choose packaging target(s) β†’ build downloadable artifacts. Clear distinction: Local / Hybrid / Hosted Wrapper.

Stack

  • Deploy: Hugging Face Space, Docker SDK (cpu-basic)
  • Backend: Python 3.11 + FastAPI (serves /api/* + built frontend static)
  • Frontend: React 18 + TypeScript + Vite (UI English, i18n-ready; German chat copy elsewhere)
  • Auth to Hub: public Spaces need no token; private Spaces accept user-supplied HF_TOKEN (never logged; docs use [ERSATZ_KEY])

Delivery modes (never mislabel)

Mode Meaning Targets
Local Runs offline / as installed app (or generated project you build locally) Tauri project zip, AppImage/Windows stubs (project-only in HF)
Hybrid Local shell + embedded remote Space (iframe / API proxy) PWA, browser extensions, HTML widget
Hosted Wrapper Thin client that always needs the live Space URL Android Capacitor debug APK (or project zip fallback)

Extensions / PWA / HTML widget are Hybrid (or Hosted Wrapper if they only iframe).
Tauri generator is Local project β€” we ship source + scripts, not a claimed binary unless built.

API

  • POST /api/analyze { url, hf_token? } β†’ Space metadata + recommended targets
  • POST /api/build { url, targets[], options?, hf_token? } β†’ { build_id }
  • GET /api/build/{id} β†’ status / artifacts
  • GET /api/build/{id}/logs β†’ text logs
  • GET /api/build/{id}/download?target= β†’ zip/xpi
  • DELETE /api/build/{id} β†’ cleanup

Converters (Converter interface)

html_widget, pwa, firefox_ext, chromium_ext, tauri, android (Capacitor project) β€” full MVP.
Stubs: linux_appimage, windows_portable β†’ clear "project-only / not in HF env". Android prefers a debug .apk when SDK is in the Docker image; falls back to project zip. Never claims Local offline model APK.

Security

  • Builds under /tmp/spaceforge/{id} or /data/builds/{id} with TTL cleanup
  • Zip-slip protection, path validation, size/timeouts
  • No untrusted code exec in main process; no privileged Docker
  • Secrets never logged

File tree

spaceforge/
β”œβ”€β”€ SPEC.md
β”œβ”€β”€ RESULT.md
β”œβ”€β”€ README.md
β”œβ”€β”€ README_HF.md          # Space card README with YAML frontmatter
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ .dockerignore
β”œβ”€β”€ requirements.txt
β”œβ”€β”€ backend/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ main.py
β”‚   β”‚   β”œβ”€β”€ config.py
β”‚   β”‚   β”œβ”€β”€ api/routes.py
β”‚   β”‚   β”œβ”€β”€ providers/huggingface.py
β”‚   β”‚   β”œβ”€β”€ converters/
β”‚   β”‚   β”‚   β”œβ”€β”€ base.py
β”‚   β”‚   β”‚   β”œβ”€β”€ registry.py
β”‚   β”‚   β”‚   β”œβ”€β”€ html_widget.py
β”‚   β”‚   β”‚   β”œβ”€β”€ pwa.py
β”‚   β”‚   β”‚   β”œβ”€β”€ firefox_ext.py
β”‚   β”‚   β”‚   β”œβ”€β”€ chromium_ext.py
β”‚   β”‚   β”‚   β”œβ”€β”€ tauri.py
β”‚   β”‚   β”‚   β”œβ”€β”€ mobile/android.py
β”‚   β”‚   β”‚   └── stubs.py
β”‚   β”‚   β”œβ”€β”€ security/zipsafe.py
β”‚   β”‚   └── services/builds.py
β”‚   └── tests/
β”œβ”€β”€ frontend/             # Vite React TS
β”œβ”€β”€ templates/            # Generator templates
└── scripts/cleanup_ttl.py