Avalon Build Package
Tech Stack
Architecture decisions, inference API strategy, latency budget, and what is reusable beyond Avalon. Rev D added Device Reality and Safety and Abuse sections because both affect the build, not just the business.
API
Inference delivery model
~$0.15
Estimated per-session API cost
<20s
Target time to first render
4
Reusable capabilities beyond Avalon
Inference (D-06)
Image generation runs via a third-party inference API. At roughly $0.03/image, 4 variants + segmentation costs about $0.15/session. The versioned engine contract (E-09) is what makes switching providers a config change rather than a re-integration.
1
Replicate
Per-call pricing, no provisioning. Wide model selection including SDXL-class inpainting. Good fit for beta and early production. Zero-retention contract required before handling selfie data.
2
Together AI
Competitive pricing on diffusion models, batch support, and a stronger enterprise data-handling posture. Better option if volume warrants a committed spend tier.
3
fal.ai
Lowest latency on SDXL-class models in current benchmarks. Queue-based with streaming results, which fits the parallel variant pattern. Recommended for evaluation in Phase 1 bake-off. Recommended.
Compliance coupling: The user's selfie reaches the inference vendor's infrastructure. That is directly in tension with treating selfies as the most restricted data class. The vendor selection (D-06) and the compliance posture (D-04) are the same decision. Require a zero-retention, no-training contract and name the vendor in consent text before handling real user data.
Stack
| Layer | Technology | Notes |
|---|---|---|
| Client | React + TypeScript, Vite, mobile-first PWA Tailwind + GRID-HANDOFF-AVALON-DESIGN-001 tokens On-device WASM face landmarking (MediaPipe Tasks) |
PWA over native: one codebase, no app store review cycle on a product whose consent flow will change several times in the first months. Native (A-11) when retention justifies it. Landmarks discarded immediately, never transmitted. |
| API | TypeScript API (Fastify or Hono) | Transactional surface only. Keeps the render pipeline separate from the HTTP surface. |
| Orchestration | Python worker (render pipeline) Job queue and workflow engine Model routing layer |
CV and diffusion ecosystem is Python. Fighting that costs more than the polyglot boundary. |
| Consent data | Postgres | Consent records do not go in a graph. They need to be provably immutable and queryable under subpoena. ACID required. |
| Knowledge graph | Neo4j | Style taxonomy, stylist graph, SUITS weighting, catalog relationships. Dedicated instance with backups. |
| Telemetry | ClickHouse | Hard exclusion filter on image payloads (P-03). Verify that filter empirically. An assertion in a doc is not a control. |
| Object store | Self-hosted MinIO or Cloudflare R2 | Enforced lifecycle TTL and encryption at rest. Decision gates on D-06 and D-04 together. |
| Segmentation model | Off-the-shelf face-parsing at MVP. Fine-tuned Phase 3 (E-11). | Fine-tune on proprietary textured-hair data. Largest quality improvement in the package is here, not in the generation model. |
| Generation model | SDXL-class inpainting + depth control + image-prompt adapter Delivered via inference API (Replicate, fal.ai, or Together AI) |
Vendor selected by bake-off against a held-out set of textured-hair subjects (4A–4C), not by benchmark reputation. Do not select a model whose demo gallery is entirely light-skinned. Zero-retention contract required before handling real user selfies. |
| Platform | Cloudflare (DNS, WAF, image delivery) SOPS/age Vault (secrets) k3d/ArgoCD |
Stripe at Phase 4. |
Device Reality (Rev D)
The stack assumes a decent front camera, WASM on-device landmarking, and a PWA. Each assumption has a cost that is not evenly distributed.
- On-device landmarking is slow on low-end Android. WASM face-mesh inference that feels instant on a recent iPhone can take seconds on a budget Android device. Test on cheap hardware in Phase 1, not at beta. If too slow, the fallback is server-side landmarking, a materially worse compliance position (see D-04).
- PWA install friction on iOS is real. Add-to-home-screen is not discoverable. Plan for most users staying in the browser. Design the browser experience as the primary one, not a degraded path.
- Camera quality is a fairness problem, not just a quality problem. Low-light performance on darker skin is worse on cheaper sensors. A naive quality gate threshold will reject a disproportionate share of the intended audience before the model ever runs, while the model itself is fair. Requirements (doctrine C16, feature P-12): tune the quality gate against real photos from low-end hardware, instrument rejection rate by skin tone, prefer coaching and re-capture over rejection, treat a rising rejection rate in any cohort as a defect.
Safety and Abuse (MVP, not hardening)
An open image-generation endpoint attracts misuse. This is feature P-14 and it is MVP. Minimum stack:
- Input classification before generation (prohibited content, third-party face uploads flagged by attestation flow)
- Output classification before delivery
- Logging of both, without retaining the images themselves past the standard TTL
- A named human who owns reports and incidents. Not a queue nobody watches.
Latency Budget
Target: first variant visible in under 20 seconds, all four in under 45. Variants generate in parallel and stream to the client as each completes. Don't make her wait for all four; the perceived wait is the time to the first image. If budget cannot be met, reduce variant count before reducing quality.
Client quality gate and on-device landmarking
<1s (on-device)
Upload
1–3s
Segmentation
1–3s
Generation, per variant (run in parallel)
5–15s each
Face Lock composite + fidelity gate + edge blend
<1s
Delivery
<1s
Reuse Beyond Avalon
What is actually reusable beyond Avalon, in order of value. The visualizer UI itself is the least reusable and least defensible part.
01: Highest value
Render engine contract (E-09)
Masked-region image transformation service with identity-preservation guarantee and automated fairness gate. Directly reusable for any try-on or visualization product, and licensable (R13).
02
Consent and retention architecture (CN-01–CN-04)
Every product that touches biometric or sensitive personal data needs this. Build it once, properly, here, because here is where the exposure is highest.
03
Fidelity eval pattern (P-06)
Automated check that a generative pipeline is not degrading outputs for a demographic. Generalizes far past hair. A credible thing to be able to show an enterprise client.
04
Feasibility pattern (F-01)
"Can this person actually get this outcome" sitting on top of a generative "what would it look like." Transfers to any product where the pretty picture and the real-world constraint can diverge, which is most of them.