Spaces:
Paused
Paused
|
Download docs/ARCHITECTURE.md from 2Btainment/absolution-omega: direct link, hf CLI and curl.
- Browser
- Download file 3.56 kB
-
https://huggingface.co/spaces/2Btainment/absolution-omega/resolve/main/docs/ARCHITECTURE.md
- Command line
-
hf download hf://spaces/2Btainment/absolution-omega/docs/ARCHITECTURE.md
-
curl -L -o ARCHITECTURE.md https://huggingface.co/spaces/2Btainment/absolution-omega/resolve/main/docs/ARCHITECTURE.md
3.56 kB
| # Architecture decision record — Vertical Slice 0.1 | |
| ## ADR-001: Scope before architecture inflation | |
| Decision: minimal Python backend + vanilla TypeScript-free browser JS. | |
| Reason: enables actual audio processing and measured test coverage with | |
| no JavaScript package registry, no cloud account, no remote API call. | |
| Trade-off: production hybrid stack would benefit from typed React/Next.js, | |
| Tauri, durable workers, auth and an operations/data platform. | |
| ## ADR-002: HPSS first, neural adapter second | |
| HPSS is reproducible and needs no downloaded weights. It is a | |
| spectrogram-derived harmonic-vs-percussive decomposition, not a way to | |
| extract arbitrary instruments. An optional `demucs.api.Separator` | |
| adapter can produce neural drums/bass/other/vocals given trusted weights. | |
| The trained model branch is not yet validated against provided checkpoints. | |
| ## ADR-003: Explicit residual as a source of truth | |
| Input `x` and estimated stems `s_i` are same-rate, same-shape float64. | |
| Compute `residual = x - sum(s_i)`. Check mixture closure in float64 and | |
| publish actual measured maximum error. Never infer source isolation quality | |
| from that identity. For Demucs resample stem outputs back to source rate, | |
| keeping frame positions and noting resampler effects. | |
| ## ADR-004: Immutable user asset | |
| Original is stored as imported, with SHA256, then separate normalized | |
| decoded signals are used for processing. Previews are lossy relative to | |
| float64 working precision, specifically 16-bit PCM. Masters are FLOAT WAV. | |
| Project manifests are updated by atomic file replace. | |
| ## ADR-005: Local-only, no telemetry, no network model access | |
| Default host is 127.0.0.1 for the documented startup. No outbound network | |
| calls, silent checkpoint downloads, analytics or license bypass. No auth, | |
| therefore this release must NOT be accessible on a network untrusted by | |
| the operator. Do not enable public sharing without threat modeling, | |
| authentication, quotas, persistent queues and proper isolation. | |
| ## Proposed data entities (not yet a database schema) | |
| Project, InputAsset, SignalAnalysis, ProcessingJob, ModelManifest, | |
| StemAsset, ResidualAsset, TransformationGraph, QualityReport. | |
| Manifest.JSON currently contains a subset, storing only one input per project. | |
| ## Measurable acceptance criteria for v0.1 | |
| - Full import → HPSS → stem preview → export runs via actual HTTP. | |
| - 8 automated tests pass on compatible development runtime. | |
| - HPSS output samples have input shape and sample rate. | |
| - Sample-space closure passes tolerance 1e-8. | |
| - Original source SHA-256 persists in manifest. | |
| - Invalid audio and unsupported methods fail with errors. Long tracks are accepted | |
| within the configurable upload-size quota and HPSS is processed in chunks. | |
| - Local run does not require an external service or pretrained models. | |
| ## Iteration risk register | |
| 1. Native library & optional Demucs package version incompatibility. | |
| 2. In-memory job loss on process restart and possible concurrent file reads. | |
| 3. No auth; local single-user only. | |
| 4. Memory pressure for long/high-rate files. | |
| 5. Coarse HPSS cannot reliably resolve individual instruments. | |
| 6. DSP reconstruction check does not measure separation quality. | |
| 7. Future source datasets/checkpoint licenses require explicit review. | |
| ## API security improvement checklist | |
| Add authentication and rate limits before remote access; CSRF defenses; | |
| secure cookies; isolated file processing; proactive MIME/codec scanning; | |
| resource quotas; job cancellation; audit logs; secrets management; | |
| versioned asynchronous job persistence; signed artifacts. | |