docs/backend-v0.md

# NaturalCAD Backend v0

## Goal

Build a low-cost backend for NaturalCAD that is safe enough for an MVP:
- public UI on Hugging Face Spaces
- hosted inference on Hugging Face
- no important execution on Noah's laptop
- no public arbitrary code execution
- logs, metadata, and artifacts stored off-machine

## Guiding priorities

1. Keep costs low
2. Prevent spam and abuse
3. Keep secrets off the frontend
4. Avoid exposing raw Python execution to the public
5. Keep the system simple enough to actually ship

## Recommended stack

### Frontend
- Hugging Face Space
- current Gradio app is the fastest path

### Backend API
- FastAPI deployed on Fly.io
- reason: build123d and worker logic are already Python-adjacent, so this reduces stack complexity while giving us a sturdier app host for API + worker processes

### Inference
- Hugging Face Inference Endpoint or hosted HF model endpoint
- prefer free or low-cost model path for MVP

### Database
- Supabase Postgres
- reason: structured job records, artifact metadata, and status transitions fit naturally in Postgres, and Supabase gives a good hosted dashboard with low MVP friction

### Object storage
- hosted object storage, not local disk
- S3-compatible storage is preferred

### Worker
- isolated Python worker for geometry generation
- build123d execution should happen here, not in the public frontend tier

## Trust boundaries

### Hugging Face Space
Allowed:
- collect prompts
- submit jobs to backend
- display status and results

Not allowed:
- store backend secrets
- directly execute build123d jobs
- write directly to database with privileged credentials
- be the source of truth for rate limiting or audit policy

### Backend API
Responsible for:
- request validation
- rate limiting
- job creation
- inference calls
- schema validation
- queue handoff
- database writes
- artifact metadata
- audit logs

### Worker
Responsible for:
- consuming approved jobs
- generating structured CAD outputs
- optionally translating internal spec to build123d code
- exporting STL/STEP
- uploading artifacts to hosted storage
- updating job status

### Database
Store:
- job records
- prompt text
- derived structured spec
- status transitions
- artifact metadata
- session or user metadata
- audit events
- rate-limit counters if needed

### Object storage
Store:
- STL files
- STEP files
- previews
- log blobs if needed

## Public input model

### Public API rule
Public users submit prompts, not arbitrary code.

That means:
- user sends prompt text
- backend calls model
- model returns structured data or a constrained internal representation
- worker generates geometry from approved internal data

### Internal flexibility
Internally, NaturalCAD may still generate build123d code if that helps implementation.
But code generation should stay behind the backend/worker boundary, not exposed as a public execution surface.

## Job lifecycle

Use these statuses:
- `submitted`
- `validated`
- `queued`
- `running`
- `completed`
- `failed`

Optional later:
- `blocked`
- `expired`
- `canceled`

## Minimal API shape

### `POST /jobs`
Create a job.

Input:
- prompt
- optional session id
- optional client metadata

Server actions:
- validate payload
- apply rate limit
- create job record
- call inference or enqueue pre-inference flow

Returns:
- job id
- status

### `GET /jobs/{job_id}`
Fetch job status.

Returns:
- current status
- error info if failed
- artifact metadata if completed

### `GET /jobs/{job_id}/artifacts`
Return artifact metadata and signed URLs if applicable.

### `GET /health`
Basic health check.

## Suggested Postgres tables

### `jobs`
Columns:
- `id`
- `created_at`
- `updated_at`
- `status`
- `prompt`
- `normalized_prompt`
- `spec_json`
- `error_text`
- `client_session_id`
- `ip_hash`
- `model_info_json`

### `artifacts`
Columns:
- `id`
- `job_id`
- `kind` (`stl`, `step`, `preview`, `log`)
- `storage_key`
- `size_bytes`
- `created_at`
- `expires_at`

### `audit_events`
Columns:
- `id`
- `job_id`
- `event_type`
- `created_at`
- `details_json`

### `rate_limits`
Optional if not handled elsewhere.

## Queue strategy

For MVP, keep it simple.

Options:
1. DB-backed queue with polling
2. lightweight Redis queue later if needed

Recommendation:
- start with a DB-backed queue and one worker
- upgrade only when traffic justifies it

## Low-cost implementation order

### Phase 0
- keep Gradio frontend
- do not deploy public raw code execution

### Phase 1
- create FastAPI service on Fly.io
- add `POST /jobs` and `GET /jobs/{job_id}`
- connect Supabase Postgres
- add simple rate limiting

### Phase 2
- connect HF inference endpoint
- store prompt, status, and response metadata
- validate returned structured output

### Phase 3
- add Python worker
- generate artifacts
- upload artifacts to hosted storage
- return signed artifact links

### Phase 4
- tighten retention, add auth tiers, add cancellation, add preview generation

## Spec direction for the next phase

NaturalCAD should move next toward a **loose compositional / semantic JSON spec** rather than a rigid family-first schema.

Reason:
- rigid family routing too early will bias the model toward repetitive safe defaults
- concept-grade generation needs room for novelty, unexpected topology, and broader prompt coverage
- reuse and dedupe should exist, but as later optimization layers rather than the main creative frame

Recommended next spec target:
- `intent`
- `semantic_part`
- `family_hint` (optional, not dominant)
- `geometry`
- `dimensions`
- `constraints`
- `style`
- `dedupe`

Reference:
- `docs/compositional-spec-v1.1.md`

## What not to do in v0

- no public arbitrary Python execution
- no local laptop as production backend
- no secrets in frontend code
- no unlimited artifact retention
- no complicated microservice split

## Default recommendation

NaturalCAD v0 should ship as:
- Hugging Face Space frontend
- FastAPI backend on Fly.io
- Supabase Postgres
- hosted object storage
- one Python worker
- strict prompt-only public interface