# Milestone 3 product architecture

Date: 2026-07-19
Status: implemented and locally validated

## Boundary

Milestone 3 is a product layer around the promoted `build_week_vnext` workflow.
It does not duplicate reconstruction, design, rendering, review, repair, or
release logic in the browser.

```text
browser
  -> vinext product UI
  -> local product API
  -> durable job record + isolated upload
  -> scripts/chartsmith_vnext.py
  -> canonical run artifacts
  -> presentation projector
  -> polished stage journey in the browser
```

The accepted examples and live runs use the same presentation schema. This is a
deliberate integrity property: examples cannot receive a handcrafted narrative
that a genuine run could never produce.

## Product UI

Location: `app/web/`

The interface provides:

- an immediate source/redesign transformation;
- ten complete accepted example journeys;
- a real image upload path;
- truthful current-stage and completed-stage presentation;
- user-facing reconstruction, concepts, rendered candidates, review findings,
  repairs, and final gates;
- refresh-safe restoration of the most recent live run;
- responsive desktop and mobile layouts;
- an evidence section comparing a fair direct single-call baseline with the
  complete Chartsmith result.

The primary experience never renders raw workflow JSON, prompts, logs, tokens,
machine paths, or stack traces.

Static example data is generated into `app/web/public/data/examples.json`.
Selected chart images and candidate evolution are copied under
`app/web/public/examples/`. These are generated presentation assets, not an
alternative evidence source.

## Presentation projector

Location: `scripts/chartsmith_web.py`

The projector reads the active `vnext-2026-07-19` artifact contract and emits a
versioned presentation object. It:

- locates the selected concept without inferring from prose;
- computes reconstruction confidence from recorded mark confidence;
- maps workflow artifacts into seven stable user-facing stages;
- exposes concrete review findings and repair history;
- attaches only allowlisted image artifacts;
- marks a run complete only when the canonical manifest is accepted;
- sanitizes failures into a recovery-safe message;
- removes local paths and machine-oriented field names from the product view.

Static examples call this projector during packaging. Live API responses call it
against the in-progress run directory.

## Local durable run service

Location: `scripts/chartsmith_web.py serve`

The service:

- binds to `127.0.0.1:8765` by default;
- accepts PNG, JPEG, or WebP images up to 12 MB;
- verifies decoded image type, dimensions, and pixel count;
- creates isolated, unpredictable run identifiers;
- records web job metadata under ignored `runs/build_week/web_jobs/`;
- stores source uploads under ignored `runs/build_week/web_uploads/`;
- launches no more than one full workflow concurrently;
- launches the promoted runner without modifying its contracts;
- keeps the expensive run independent of a browser connection;
- serves only explicitly allowlisted image artifacts from a run;
- limits cross-origin browser access to the local product origin.

The browser stores only the most recent run identifier. This is a reconnect
pointer, not authoritative workflow state. Canonical artifacts and durable job
metadata remain on the filesystem.

## Progress truth

There is no model-authored percentage or synthetic countdown.

The projector determines the current stage from validated artifact presence,
manifest state, review decisions, candidate modification order, and final
evaluation. A stage is presented as complete only after its contracted artifact
exists and can be read.

The stable product vocabulary is:

1. input accepted;
2. perceptual reconstruction;
3. design exploration;
4. rendering;
5. independent inspection;
6. targeted repair;
7. release decision.

## Differentiation evidence

Location: `scripts/run_single_call_baseline.py`

The controlled baseline uses:

- the same source image;
- GPT-5.6 Sol;
- one fair, open-ended request to improve the chart;
- one built-in image-generation call;
- no structured reconstruction artifact;
- no multiple-concept contract;
- no rendered-image review or repair.

An independent GPT-5.6 comparison sees the source, direct baseline, and
Chartsmith result. It is explicitly instructed to give the baseline full credit
and not prefer complexity by assumption. The product presents only findings
supported by that retained evaluation.

## Start and stop

`scripts/start_chartsmith_app.py` is the single local product entry point. It
refreshes examples, resolves the supported Codex executable, and owns the web
and API child processes so one interrupt stops both.

The interface can also be built and explored without the API. In that state the
ten accepted examples remain complete and the Local edition handoff truthfully
reports that hosted generation is off, removes the unavailable upload control,
and provides the complete source bundle, requirements, and one-command setup.

## Hosting boundary

The Sites project registered in `app/web/.openai/hosting.json` is deployed as a
public, evidence-rich showcase at
`https://chartsmith-build-week.sseo.chatgpt.site`.

The current hosted web runtime cannot execute a long-running local Python/Codex
process. Public live uploads therefore require a later authority and architecture
decision covering hosted workers, durable storage, model credentials, spending,
and concurrency. Until then:

- present the hosted section as a **Local edition** handoff;
- disable and remove the upload control when the genuine engine is unavailable;
- direct judges to the ten completed journeys and the local-run path;
- do not replace the genuine workflow with a simulation;
- preserve the API/presentation boundary so hosted job infrastructure can
  replace the local service without redesigning the UI.
