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