Spaces:
Sleeping
Sleeping
File size: 6,177 Bytes
f74bce1 cbb6866 413c5fe 40cb975 bd6cbae 6609140 f74bce1 7700633 | 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 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 | # ProofFrame Technical Spec
## Architecture
```text
Browser UI
|
FastAPI app
|-- Campaign service
|-- Generation service
| |-- MockMediaProvider
| |-- GenblazeMediaProvider
|-- Storage service
| |-- LocalStorageBackend
| |-- B2StorageBackend
|-- Manifest service
|-- Submission gate service
|-- SQLite repository
```
## Data Model
### Campaign
- `id`
- `title`
- `brief`
- `audience`
- `tone`
- `created_at`
### Asset
- `id`
- `campaign_id`
- `kind`: image, video, audio, text
- `status`: draft, approved, rejected
- `prompt`
- `provider`
- `model`
- `storage_backend`
- `storage_key`
- `public_url`
- `sha256`
- `generation_metadata`
- `risk_note`
- `created_at`
### Manifest
- `manifest_version`
- `campaign`
- `assets[]`
- `exported_at`
- `app_version`
## API Draft
| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/` | Serve the Proof Ledger browser UI. |
| `GET` | `/api/health` | Runtime health and adapter availability. |
| `GET` | `/api/submission/gate` | Return fail-closed final submission readiness for task gates, Devpost packet, live proof evidence, and final report artifacts. |
| `GET` | `/api/judge/brief` | Return the public-safe judge brief artifact that powers the first-screen Judge Brief panel. |
| `GET` | `/api/judge/crosswalk` | Return the public-safe judge criteria crosswalk artifact that powers the first-screen Criteria Crosswalk panel. |
| `GET` | `/api/judge/recording` | Return the public-safe recording runbook artifact that powers the first-screen Recording Runbook panel. |
| `GET` | `/api/judge/devpost` | Return the public-safe Devpost form kit artifact that powers the first-screen Devpost Kit panel. |
| `GET` | `/api/judge/submission-checklist` | Return the public-safe Devpost submission checklist artifact that powers the first-screen Submit Checklist panel. |
| `POST` | `/api/campaigns` | Create campaign. |
| `GET` | `/api/campaigns` | List campaigns. |
| `POST` | `/api/campaigns/{id}/generate` | Generate variants. |
| `POST` | `/api/demo/judge-packet` | Create a one-click judge-ready local demo packet. |
| `POST` | `/api/assets/{id}/status` | Approve/reject asset. |
| `GET` | `/api/campaigns/{id}/manifest` | Return manifest JSON. |
| `POST` | `/api/campaigns/{id}/export` | Export packet. |
| `GET` | `/api/campaigns/{id}/packet.zip` | Download manifest, README, and available local media as an evidence packet. |
## Review Console
The browser UI includes local-only review operations over the in-memory asset set:
- scorecard counts for total, approved, draft, rejected, and decision coverage
- status filter for all/draft/approved/rejected
- search across prompt, provider, model, storage backend, storage key, checksum, and risk note
- copy-safe evidence summary that includes campaign id, counts, backend names, first checksum, and storage key, but no credentials or signed URLs
## Submission Gate Dashboard
The browser sidebar includes a final gate panel backed by `GET /api/submission/gate`:
- required final tasks: T020, T021, T040, T041, T041A, and T042
- Devpost packet presence and claim mode
- final live proof evidence status for B2 storage plus Genblaze generation
- final report artifacts for secret scan, submission audit, and Devpost submission receipt
- next-action copy for whichever final blocker remains first
The gate intentionally stays in `pre_live_safe` mode until all required tasks are done, `docs/assets/final-live-proof-evidence.json` proves B2 plus Genblaze with nonempty sanitized object/checksum fields, and the final secret scan, submission audit, and Devpost receipt reports all declare the expected schema with `ok=true`.
## Storage
Local mode:
- Writes media and manifests under `var/storage`.
- Used by tests, demo fallback, and contributors without credentials.
B2 mode:
- Uses S3-compatible settings:
- `B2_ENDPOINT_URL`
- `B2_S3_ENDPOINT_URL` as an accepted alias
- `B2_BUCKET`
- `B2_KEY_ID`
- `B2_APPLICATION_KEY`
- `B2_APP_KEY` as an accepted alias
- Credentials are environment-only.
- If required variables are missing, B2 mode must be unavailable rather than silently falling back during final verification.
- Current status: code-level backend and fake-client tests exist. Live B2 bucket verification is still required before public submission claims.
## Generation
Mock mode:
- Creates deterministic SVG/PNG-like artifacts and metadata from the prompt.
- Guarantees repeatable tests.
Genblaze mode:
- Uses the official Genblaze `Pipeline` API with `GMICloudImageProvider`.
- Records provider/model/run/manifest metadata in the manifest without storing raw provider URLs.
- Must never persist raw secrets.
- Current status: code-level provider path exists and fails closed without packages/config. Live official Genblaze package/provider route is still required before public submission claims.
## Frontend Direction
The selected interface is Proof Ledger, a restrained audit-and-approval board for media approvals:
- Dense but calm asset ledger.
- Visible storage and manifest details.
- Strong first-viewport product signal: ProofFrame, campaign status, asset packet.
- No generic purple AI hero.
- Use an `index.html` entry file.
- Include subtle "Created By Deerflow" signature as required by the frontend-design skill when generated frontend code is added.
## Security
- `.env` is ignored.
- Provide `.env.example`.
- Add a secret scan before final submission.
- Do not print full storage keys or signed URLs in test logs unless sanitized.
## Verification Gates
- Unit tests for task ledger, manifest, storage adapters.
- API smoke for `/api/health`.
- Browser smoke for create/review/export happy path.
- Docker build and local run.
- Submission audit against Devpost requirements.
- Submission gate API and UI checks.
- Schema-stamped judge crosswalk from official criteria to evidence, safe claims, final gates, and demo shots.
- No-secret final rehearsal checklist before credential entry and Devpost submission.
- No-secret Devpost web submission checklist before pressing the final submit button.
- Public demo video URL check for token-free, reachable final video evidence.
|