Spaces:
Running
Running
File size: 3,319 Bytes
3806142 dbc2744 3806142 3da9c98 dbc2744 3806142 3da9c98 3806142 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | # 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
```
|