# 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 ```