System Requirements Document for terra-images

1. Introduction

terra-images is a first-party web application for a Dataset Owner — a hands-on practitioner who already possesses a labeled image dataset and wants a machine learning model built from it that labels images. The product's intent is a workshop, not a marketplace: the owner brings raw material (labeled images), the application plainly tells them what else it still needs from them, they supply it, and the application returns a trained image-labeling model as a built artifact.

The audience is a single practitioner role who works with their own gear and their own data, values being told plainly what is missing before work begins, and expects the resulting model to be traceable to the dataset it was trained on. The product's governing constraint is stated by the user directly: if anything is required from the owner, it must be requested from them first so they can provide it — nothing is silently assumed, and no training proceeds on incomplete inputs.

2. System Overview

terra-images is delivered as a custom first-party web application with an application-owned identity boundary and a shared backend that performs durable dataset storage, requirement tracking, and model training/inference work.

Current actors

• Dataset Owner (active human persona) — the sole accepted human actor. They enroll, provide a labeled image dataset, answer the application's requests for additional required inputs, start training, and obtain and use the trained image-labeling model.
• Training/Inference Engine (non-persona system actor) — the backend process that consumes the owner's labeled dataset and produces a trained model artifact and its metrics.
• Object Storage (non-persona system actor) — durable storage for uploaded images, label files, and trained model artifacts.

Accepted behavior in scope

1. Self-service enrollment and returning verification for the Dataset Owner.
2. Supplying a labeled image dataset (images plus their labels) and revisiting it.
3. The application surfacing every additional input it requires from the owner before training, and the owner supplying those inputs.
4. Starting training on the owner's labeled dataset and obtaining the resulting trained image-labeling model, with its training state and outcome observable to the owner.

Narrow exclusions

• No defect-detection, PLC, camera, reject-mechanism, or factory-automation capability is part of terra-images. The uploaded automotive-plastic proposal is background context describing a downstream application domain; it does not create pages, modules, or hardware integrations in this product.
• No annotation/labeling editor is in scope: the owner already has labeled data and supplies it; the product does not ask them to draw new labels.
• No billing, team management, role-based permissions, marketplace, or third-party model-sharing capability is in scope.

2a. Product Interpretation and Delivery Boundary

terra-images is a current, single-tenant-per-owner, application-owned product. The owner's datasets, outstanding requirements, and trained models are durable, private, owner-specific state; therefore the application owns identity: an anonymous visitor can read the public entry surface, and must establish or verify identity before reaching Datasets, Requirements, or Models. Identity establishment is self-service (Sign Up) with returning verification (Login); there is no invitation, provisioning, or deployment-bootstrap path, and no differentiated roles or permissions — every authenticated user is a Dataset Owner acting only on their own state.

The delivery boundary is deliberately narrow. The application owns the human workflow end to end: intake of the labeled dataset, the explicit request-for-inputs loop, training initiation, and delivery of the trained model. Heavy computation (training and inference) is a backend responsibility of the same application, not a separate product surface. Nothing in the current scope is deferred to a future horizon; the automotive-plastic inspection domain described in the uploaded proposal is explicitly not part of this product's current or future delivery boundary — it is context for why image-labeling models matter, not a requirement.

2b. Source Content Inventory

Not applicable — no reference directive in this request declares a content_source.

2c. Page Content and Component Coverage

The page inventory is the supplied final page contract, preserved exactly and in order: Landing, Login, Sign Up, Datasets, Requirements, Models.

Landing

• Purpose and access: Anonymous public entry surface. Explains that terra-images trains an image-labeling model on the owner's own labeled image dataset. No protected state is visible here.
• Information and state: Product statement; the three-step workflow band (01 Datasets → 02 Requirements → 03 Models); a plain-talk line about bringing your own labeled images and being told what's still missing; the primary call to action.
• Primary actions: "Start with your dataset" → Sign Up. Supporting action: "I already have an account" → Login.
• Domain entities referenced: Dataset (conceptual), Requirement (conceptual), Model (conceptual) — no owner data is loaded.
• Component responsibilities: Ruled top navigation bar with badge wordmark; asymmetric hero (oversized slab headline, forest-green statement block, orange CTA); rotated halftone contact-sheet of representative labeled-image thumbnails with tag pictograms; circular stamped badge; numbered workflow band with step 01 marked active.
• States: Static success state only. No loading, empty, or error states apply because no owner data is fetched. If the visitor is already authenticated, the CTA routes to Datasets instead of Sign Up.

Login

• Purpose and access: Anonymous identity-verification surface for a returning Dataset Owner. Cannot itself be reached only after authentication.
• Information and state: Email and password fields; inline validation messages; a general failure message for rejected credentials.
• Primary actions: Submit credentials to verify identity and continue to Datasets. Supporting action: link to Sign Up for a visitor without an account.
• Domain entities: Owner identity (email, credential).
• Component responsibilities: Ruled form panel with label/value rows; rectangular submit button with offset shadow; error banner region.
• States: Loading — submit disabled with a progress indication while verification runs. Empty — fields blank on first arrival. Success — session established, redirect to Datasets (or to the originally requested protected page). Error — invalid credentials show a non-revealing message and preserve the entered email; network failure shows a retryable message. Recovery — the owner may resubmit or navigate to Sign Up.

Sign Up

• Purpose and access: Anonymous self-service enrollment surface. Creates the owner's application identity so durable datasets, requirements, and models can be privately owned.
• Information and state: Email, password, and password confirmation fields; validation rules shown inline; a statement that the account owns the datasets and models created under it.
• Primary actions: Create the account and continue to Datasets. Supporting action: link to Login for a returning owner.
• Domain entities: Owner identity.
• Component responsibilities: Ruled form panel; inline field validation; rectangular submit button with press interaction; error banner region.
• States: Loading — submit disabled during account creation. Empty — blank fields. Success — account created and session established, redirect to Datasets with an onboarding prompt to upload the first dataset. Error — duplicate email, weak password, or mismatch between password fields shown inline; network failure retryable. Recovery — correct the field and resubmit, or switch to Login if the account already exists.

Datasets

• Purpose and access: Protected surface (requires login). The owner provides and revisits their labeled image dataset, which is the input to model building.
• Information and state: List of the owner's datasets with ruled label/value rows — dataset name, image count, label count, label format, upload date, and status (e.g., Uploading, Ready, Incomplete). Per-dataset detail showing a halftone contact sheet of the dataset's own image thumbnails with their labels, plus a completeness summary stating whether images and labels are both present and matched.
• Primary actions: Create a dataset and upload labeled images (images plus their label files, or an archive containing both). Open a dataset to review it. Supporting actions: rename a dataset; delete a dataset that has no trained model depending on it.
• Domain entities: Dataset (name, images, labels, label format, counts, status, owner).
• Component responsibilities: Ruled dataset table with tabular numerals and all-caps column headers; upload panel with drag-and-drop and file picker; per-file progress rows; contact-sheet thumbnail grid; completeness summary panel; numbered workflow band with step 01 filled.
• States: Loading — skeleton ruled rows while the dataset list is fetched. Empty — no datasets yet: a plain-talk panel explaining that the owner's labeled images are the starting material, with the upload action. Success — dataset listed as Ready with counts and thumbnails. Error — unsupported file type, unreadable archive, or image/label mismatch reported per file with the offending files named; upload interruption shows a retry action that resumes or restarts that upload. Recovery — remove or replace failed files and re-upload; a partially uploaded dataset remains visible as Incomplete and cannot be used for training until resolved.

Requirements

• Purpose and access: Protected surface (requires login). Surfaces every additional piece of information or input the application needs from the owner before training can begin, so the owner can supply it — implementing the user's explicit constraint that anything required is asked for first.
• Information and state: A checklist of outstanding and satisfied requirements for the selected dataset, each with a plain description of what is needed and why. Requirement kinds include: confirming the dataset is fully labeled and matched; naming the label classes present; selecting the task type the labels represent (e.g., classification or segmentation); confirming the train/validation split; and any other input the workflow determines it needs. Each item shows state Action needed (orange) or Provided (stamped with an orange check).
• Primary actions: Supply a value for each outstanding requirement (free text, selection, or file attachment as appropriate) and mark it provided. Supporting action: return to Datasets to fix the underlying dataset when a requirement cannot be satisfied from this page.
• Domain entities: Requirement (kind, description, state, supplied value, dataset reference).
• Component responsibilities: Ruled checklist with numbered items; inline input controls per item; state badges; a summary line stating how many requirements remain; the numbered workflow band with step 02 filled and step 01 stamped complete.
• States: Loading — checklist skeleton. Empty — all requirements satisfied: a confirmation panel and a direct action to proceed to Models. Success — item flips instantly to Provided with its value shown. Error — invalid value (e.g., empty class name, split percentages not summing to 100) shown inline against that item; save failure preserves the typed value and offers retry. Recovery — the owner may edit a provided value at any time before training starts.

Models

• Purpose and access: Protected surface (requires login). The owner starts training on a dataset whose requirements are all satisfied, observes training progress, and obtains the trained image-labeling model.
• Information and state: List of the owner's models with ruled label/value rows — model name, source dataset, training status (Queued, Training, Trained, Failed), started/completed timestamps, and headline metrics. Per-model detail showing the training configuration drawn from the supplied requirements, the metrics table (per-class results and overall figures), and the model artifact with its version identifier. A "model trained" seal appears on successfully trained models.
• Primary actions: Start training for a selected dataset. Open a model to inspect its metrics and artifact. Supporting action: download the trained model artifact; start a new training run from the same dataset after changing requirements.
• Domain entities: Model (name, source dataset, configuration, status, metrics, artifact, version, owner), Training Run (status, timestamps, failure reason).
• Component responsibilities: Ruled model table; "Start training" panel that names the dataset and confirms all requirements are satisfied; progress indicator with status text; metrics table with tabular numerals; artifact download control; stamped seal badge; numbered workflow band with step 03 filled and prior steps stamped complete.
• States: Loading — model list skeleton. Empty — no models yet: a panel explaining that training becomes available once a dataset is ready and its requirements are satisfied, with links to Datasets and Requirements. Success — model listed as Trained with metrics and a downloadable artifact. Error — training failure shows the recorded failure reason and a retry action; attempting to start training with unsatisfied requirements routes the owner to Requirements with the outstanding items named. Recovery — retry a failed run, or amend requirements and start a new run.

3. Functional Requirements

FR-1 — Self-service enrollment As a Dataset Owner, I should be able to create my own account so that my datasets, requirements, and models are durably and privately mine.

• Provenance: required_inference (identity continuity for durable owner-specific state).
• Lifecycle: Owner arrives anonymously at Landing → Sign Up; supplies email and password; the application creates the identity and establishes a session; the owner lands on Datasets with an empty state prompting the first upload.
• Access state: anonymous entry; protected state unavailable until the account exists.
• Failure/recovery: duplicate email, weak password, or mismatched confirmation shown inline; the owner corrects and resubmits or switches to Login.
• Continuation: first dataset upload.
• Acceptance: a new account can be created from Sign Up and immediately reaches an empty Datasets page owned by that account.

FR-2 — Returning verification As a Dataset Owner, I should be able to verify my identity on return so that I can reach my existing datasets, requirements, and models.

• Provenance: required_inference.
• Lifecycle: Owner arrives at Login, submits credentials, session established, redirected to Datasets (or the originally requested protected page).
• Access state: anonymous entry; protected pages require the verified session.
• Failure/recovery: invalid credentials produce a non-revealing error and preserve the email; network failure is retryable.
• Continuation: resume work on datasets, requirements, or models.
• Acceptance: valid credentials reach the owner's own Datasets; invalid credentials do not.

FR-3 — Provide a labeled image dataset As a Dataset Owner, I should be able to upload my labeled images — images together with their labels — so that the application has the training material it needs.

• Provenance: explicit (user states they have labeled data with images and can provide it).
• Lifecycle: Owner opens Datasets, creates a dataset, uploads images and label files (or an archive containing both); the application validates and stores them; the dataset appears with counts and a Ready or Incomplete status.
• Access state: authenticated owner only; the dataset is bound to that owner.
• Failure/recovery: unsupported types, unreadable archives, and image/label mismatches are reported per file with the offending files named; interrupted uploads are retryable; a partial dataset remains visible as Incomplete.
• Continuation: review the dataset, then proceed to Requirements.
• Acceptance: an uploaded dataset shows accurate image and label counts, its label format, and a completeness summary; an incomplete dataset is visibly incomplete and cannot be trained on.

FR-4 — Revisit and review a dataset As a Dataset Owner, I should be able to reopen a dataset and see its images, labels, and completeness so that I can confirm it is the right material before training.

• Provenance: required_inference (the owner must be able to verify the input they supplied).
• Lifecycle: Owner opens a dataset from Datasets; sees a contact sheet of its own thumbnails with labels and a completeness summary; returns to the list or proceeds to Requirements.
• Access state: authenticated owner only.
• Failure/recovery: if thumbnails fail to load, the counts and completeness summary remain readable and a retry is offered.
• Continuation: proceed to Requirements or amend the dataset.
• Acceptance: the dataset detail reflects exactly the files the owner uploaded.

FR-5 — Surface every additional required input As a Dataset Owner, I should be told plainly, before training, everything else the application needs from me so that I can provide it rather than discovering gaps later.

• Provenance: explicit (user: "if you required any thing first tell me so that i can provide as well") plus required_inference for the concrete requirement kinds.
• Lifecycle: When a dataset is selected for training, the application evaluates it and lists every outstanding requirement on Requirements, each with a plain description and an Action needed state; the owner sees the count remaining.
• Access state: authenticated owner only.
• Failure/recovery: if evaluation cannot complete, the page states that requirements could not be determined and offers retry rather than implying none are needed.
• Continuation: the owner supplies each item.
• Acceptance: no training can be started while any requirement is outstanding, and the outstanding items are named on Requirements.

FR-6 — Supply required inputs As a Dataset Owner, I should be able to provide each requested input — confirming the dataset is fully labeled and matched, naming the label classes, selecting the task type, confirming the train/validation split, and any other input the workflow asks for — so that training can proceed on complete information.

• Provenance: required_inference (indispensable mechanics for FR-5's accepted outcome).
• Lifecycle: Owner fills each checklist item and marks it provided; the item flips instantly to Provided with its value shown; the remaining count decreases.
• Access state: authenticated owner only.
• Failure/recovery: invalid values (empty class name, split not summing to 100) shown inline; save failures preserve typed values with retry; provided values remain editable until training starts.
• Continuation: when all items are provided, the owner is offered a direct route to Models.
• Acceptance: every requirement item can be supplied and shows its supplied value; the all-satisfied state is explicit.

FR-7 — Start training As a Dataset Owner, I should be able to start training on a dataset whose requirements are all satisfied so that a model is built from my labeled images.

• Provenance: explicit (build the machine learning model from the labeled image data).
• Lifecycle: Owner selects a ready dataset on Models and starts training; the application creates a training run in Queued then Training; the owner observes status and timestamps.
• Access state: authenticated owner only.
• Failure/recovery: starting with unsatisfied requirements routes the owner to Requirements with the outstanding items named; a run that fails records a failure reason and offers retry.
• Continuation: observe progress to completion.
• Acceptance: a training run is created only for a ready dataset with all requirements satisfied, and its status is observable.

FR-8 — Obtain the trained image-labeling model As a Dataset Owner, I should receive the trained model produced from my labeled data, with its metrics and a downloadable artifact, so that I have the built artifact I came for.

• Provenance: explicit (the model must label images, trained on the owner's own labeled data).
• Lifecycle: On completion the model shows Trained with a stamped seal, a metrics table (per-class results and overall figures), its source dataset, its configuration drawn from the supplied requirements, and a versioned artifact the owner can download.
• Access state: authenticated owner only; the model is bound to the owner and its source dataset.
• Failure/recovery: a failed run shows its reason and a retry action; a model whose artifact is unavailable states so and offers retry of the run.
• Continuation: download the artifact, or start a new run from the same dataset after amending requirements.
• Acceptance: a completed run yields a downloadable artifact and a metrics table traceable to the source dataset and configuration.

FR-9 — Ask before assuming As a Dataset Owner, I should never have an input silently assumed on my behalf when the workflow needs it, so that the model is built on information I actually supplied.

• Provenance: explicit (hard constraint).
• Lifecycle: Any point at which the workflow lacks a needed input produces a named requirement on Requirements rather than a default; training is blocked until it is supplied.
• Access state: applies to all authenticated owner work.
• Failure/recovery: if the workflow cannot determine what is missing, it says so and offers retry rather than proceeding.
• Continuation: the owner supplies the item and training resumes.
• Acceptance: no training run starts while any requirement is outstanding.

4. User Personas

Dataset Owner

Product context. The Dataset Owner is a hands-on practitioner who already holds a labeled image dataset — images plus their labels — and wants a machine learning model built from it that labels images. They are not arriving to annotate; they are arriving with finished raw material and a specific expectation: that the tool will tell them plainly what else it needs before it starts work. They judge the product by whether it is honest about gaps and whether the artifact it hands back is traceable to what they gave it.

Primary goal. Turn their own labeled images into a trained image-labeling model, without discovering missing inputs after the fact.

Distinct accepted responsibilities.

• Enroll once (Sign Up) and verify identity on return (Login) so their work is durably theirs.
• Upload and revisit their labeled image dataset, confirming images and labels are present and matched.
• Read the application's list of outstanding requirements and supply each one — confirming completeness, naming label classes, selecting the task type, confirming the train/validation split, and any other input the workflow asks for.
• Start training on a dataset whose requirements are satisfied, observe its progress, and obtain the trained model with its metrics and downloadable artifact.

Relevant inputs and decisions. Which dataset to train on; whether the uploaded material is complete and correctly matched; the label classes present; the task type the labels represent; the train/validation split; whether to retry a failed run or amend requirements and start a new one.

Interactions with other accepted participants. The Dataset Owner is the sole human actor. Their counterpart is the application's training/inference engine, which consumes the dataset and returns a model; the owner's side of that exchange is starting the run and reading its outcome, and the engine's side is producing status, metrics, and the artifact. There is no second human participant, no reviewer, and no approver in the accepted scope.

Observable success. The owner sees their dataset listed as ready with accurate counts, sees every requirement either Action needed or Provided, and receives a model marked Trained with a metrics table and a downloadable artifact tied to their dataset and configuration.

5. Core User Flows

Flow A — First-time enrollment and first dataset

1. The visitor arrives anonymously at Landing and reads the plain statement that terra-images trains an image-labeling model on the owner's own labeled images, with the numbered band 01 Datasets → 02 Requirements → 03 Models.
2. The visitor selects "Start with your dataset" and lands on Sign Up.
3. The visitor supplies email, password, and confirmation and submits. The application creates the identity and establishes a session.
4. The owner lands on Datasets in its empty state, which explains that their labeled images are the starting material and offers the upload action.
5. The owner creates a dataset, names it, and uploads images together with their label files (or an archive containing both).
6. The application validates the upload. Files that are unsupported, unreadable, or unmatched are named individually with an error; the owner removes or replaces them and re-uploads.
7. On success the dataset appears in the ruled table with image count, label count, label format, upload date, and status Ready.
8. Next step: the owner opens the dataset to review it, or proceeds to Requirements.

Flow B — Returning owner resumes work

1. The owner arrives at Login and submits their email and password.
2. On invalid credentials, a non-revealing error appears and the email is preserved; the owner corrects and resubmits, or follows the link to Sign Up if they have no account.
3. On success the session is established and the owner is taken to Datasets (or the protected page they originally requested).
4. The owner sees their existing datasets with their statuses and continues from wherever they left off — reviewing a dataset, supplying requirements, or checking a model.
5. Next step: whichever of Flows C, D, or E matches their outstanding work.

Flow C — Review a dataset before training

1. From Datasets, the owner opens a dataset.
2. The detail view shows a contact sheet of that dataset's own image thumbnails with their labels, alongside a completeness summary stating whether images and labels are both present and matched.
3. If the dataset is Incomplete, the summary names what is missing and the owner returns to the upload to fix it.
4. If the dataset is Ready, the owner proceeds to Requirements.
5. Next step: Flow D.

Flow D — Supply the inputs the application asks for

1. The owner opens Requirements for the selected dataset.
2. The application lists every outstanding item with a plain description of what is needed and why, each marked Action needed (orange), and states how many remain.
3. The owner works through the items: confirming the dataset is fully labeled and matched; naming the label classes present; selecting the task type the labels represent; confirming the train/validation split; and supplying any other input the workflow has asked for.
4. An invalid value — an empty class name, a split that does not sum to 100 — is shown inline against that item; a save failure preserves the typed value and offers retry.
5. As each item is supplied, it flips instantly to Provided with its value shown, and the remaining count decreases.
6. When the last item is provided, the page shows a confirmation panel and a direct action to proceed to Models.
7. Next step: Flow E. If the owner later realizes a value was wrong, they may edit it here at any time before training starts.

Flow E — Start training and obtain the model

1. The owner opens Models. With no models yet, the empty state explains that training becomes available once a dataset is ready and its requirements are satisfied, with links to Datasets and Requirements.
2. The owner selects a ready dataset whose requirements are all satisfied and starts training. If any requirement is outstanding, the application routes them to Requirements and names the outstanding items instead of starting.
3. The application creates a training run, which appears as Queued and then Training, with its start time shown.
4. The owner observes progress on the model's row and detail view.
5. On completion the model shows Trained with the stamped seal, a metrics table with per-class results and overall figures, its source dataset, the configuration drawn from the supplied requirements, and a versioned artifact.
6. The owner downloads the artifact.
7. Failure path: if the run fails, the model shows Failed with the recorded failure reason and a retry action. The owner either retries the run, or returns to Requirements to amend a supplied value and starts a new run from the same dataset.
8. Next step: the owner has the trained image-labeling model built from their own labeled data; they may start further runs from the same or another dataset.

6. Visuals, Colors and Theme

Muse and headline. Aaron Draplin — bold, honest, hand-built field-guide typography for a working image-labeling model. The register is sturdy workshop craft with a bit of pride: printed, not floated; plain talk, not marketing gloss.

Mode. Light mode only.

Color tokens (exact hex, by role).

Balance: roughly 60% cream, 25% ink/green structure, 10% surface panels, 5% orange. Never a white-first layout; no indigo or Bootstrap blue anywhere.

Typography.

• Headings and wordmark: Alfa Slab One, tight tracking (-0.01em); uppercase for section labels, sentence case for large hero lines.
• Body, UI, table data, and all-caps micro-labels: Oswald (400/500/600), micro-labels at +0.08em tracking. No light weights anywhere.
• Scale: 1.333 modular, clamp-based — display clamp(2.5rem, 8vw, 6rem) (40→96px); h2 28→48px; h3 20→28px; body 16→18px; label 12→13px all-caps. Numerals tabular throughout tables and metrics.

Shape language. Chunky 2px–3px ink borders; hard 4px corners, never pill; ruled panels and label/value rows; circular and shield badge/stamp motifs; halftone and hazard-stripe accents; thick-line icons. Buttons are rectangular with a solid offset shadow (2px 2px 0 ink) that presses flat on click.

Layout. Poster-like vertical rhythm on a strict 12-column grid with visible hairline rules between sections. Generous outer margins, dense but ordered interiors. Dashboards use ruled label/value tables, not floating cards.

Imagery. Thick-line vector pictograms (camera, tag, stack, gear, stamp); halftone-treated photographic crops of the owner's labeled image thumbnails arranged like a contact sheet; badge and sticker marks; ruled diagram panels. No glossy 3D, no gradient blobs, no stock people.

Accessibility and fit. All readable text and controls stay whole inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling via clamp; decoration and imagery may bleed, rotate, or overlap but never cover readable text or controls. Contrast of ink #1F1B16 on cream #F2E9D8 and on surface #FBF6EC is high; orange #E4572E is used for accents and large/bold text, with ink text on orange fills.

7. Signature Design Concept

The Field-Tested Contact Sheet. The Landing page is a printed poster, not a centred SaaS hero. On the left, a two-line Alfa Slab One headline — "TRAIN A MODEL ON YOUR OWN LABELED IMAGES" — sits flush-left at clamp(2.5rem, 8vw, 6rem), stacked over a solid forest-green #1E4B3A block holding a short plain-talk line about bringing your own labeled images and being told what's still missing, with the primary orange #E4572E CTA "Start with your dataset" pinned beneath it. On the right, a rotated contact sheet of halftone-treated image thumbnails with green tick and tag pictograms stamped across them bleeds off the right edge. A circular "FIELD-TESTED ML" badge, rotated -8°, overlaps the headline block's corner. The top navigation is a ruled ink bar with all-caps Oswald labels and a small badge wordmark. Beneath the hero, the numbered 01 Datasets → 02 Requirements → 03 Models band renders as ruled badge panels with step 01 filled forest green. The same circular stamp reappears as the "model trained" seal on Models, closing the loop between the promise on the poster and the artifact the owner receives.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief.

• Focal subject: the rotated contact sheet of halftone labeled-image thumbnails with green tag pictograms, bleeding off the right edge.
• Thesis: input → transformation → outcome. On load, the contact sheet snaps into place in a single restrained pass and the circular "FIELD-TESTED ML" badge presses onto the headline block's corner with a slow one-pass halftone fade — the same stamp gesture that later marks a trained model. The motion says: material in, artifact stamped out.
• Motion vocabulary: snap-in reveals with no bounce; a stamp "press" on primary buttons (translate 2px, shadow to 0); a slow one-pass halftone fade on the hero badge; instant state changes on requirement checklist items. Nothing floats; nothing parallax-drifts.
• Composed first frame: headline flush-left, green statement block and orange CTA beneath it, contact sheet already partially visible at the right edge, badge resting on the headline corner — a complete poster even before motion begins.
• Reduced-motion state: all reveals and the halftone fade drop to instant static states; the contact sheet renders fully composed and, where it would scroll, wraps into rows so every thumbnail is fully viewable.

9. Non-Functional Requirements

• NFR-1 — Ask-before-assume. Any input the workflow needs must be surfaced to the owner as a named requirement before training; no default may silently substitute for an owner-supplied value. Provenance: explicit. Rationale: the user's stated constraint.
• NFR-2 — Owner-scoped privacy. Datasets, requirements, and models are visible only to the authenticated owner who created them. Provenance: required_inference. Rationale: durable owner-specific state requires binding to the correct participant. This is ownership scoping, not differentiated permissions.
• NFR-3 — Durable state. Uploaded datasets, supplied requirement values, training runs, metrics, and model artifacts persist across sessions so a returning owner resumes exactly where they left off. Provenance: required_inference.
• NFR-4 — Traceability. Every trained model records its source dataset, the configuration drawn from supplied requirements, and a version identifier, so the artifact can be traced to the material it was built from. Provenance: required_inference.
• NFR-5 — Honest failure reporting. Upload failures name the offending files; training failures record and display a reason; indeterminate requirement evaluation says so rather than implying completeness. Provenance: required_inference.
• NFR-6 — Readable at every viewport. Headlines, labels, numbers, and controls remain whole and uncovered at 375px, 768px, and 1280px, per the creative direction's fit rule. Provenance: explicit (creative direction).
• NFR-7 — Reduced motion. All motion degrades to usable static states under prefers-reduced-motion. Provenance: explicit (creative direction).

10. Tech Stack

• Frontend: React single-page application. [Default — not specified by user]
• Backend: Python with FastAPI, serving identity, dataset intake, requirement tracking, and model/training endpoints from one shared backend process. [Default — not specified by user]
• Training and inference: Python machine learning pipeline invoked by the backend as a background worker process for training runs, so long-running training does not block request handling. [Default — not specified by user]
• Storage: Relational database for owners, datasets, requirements, models, and training runs; object storage for uploaded images, label files, and trained model artifacts. [Default — not specified by user]
• Packaging and deployment: Docker with docker-compose, defining the frontend, the shared backend, the training worker, the database, and object storage. [Default — not specified by user]

11. Assumptions and Constraints

• A-1. The Dataset Owner already possesses labeled images and supplies them; terra-images does not provide an annotation editor. Provenance: explicit.
• A-2. The owner is the only human actor; there is no reviewer, approver, or team. Provenance: required_inference from the closed persona catalog.
• A-3. Identity is application-owned and self-service, with no invitation, provisioning, or deployment-bootstrap path, and no differentiated roles or permissions. Provenance: required_inference from the planning scope's delivery shape.
• A-4. The concrete requirement kinds listed (completeness confirmation, label classes, task type, train/validation split) are the indispensable inputs the workflow needs; the application may surface additional inputs it determines are needed, and must do so rather than assume them. Provenance: required_inference bounded by the explicit ask-before-assume constraint.
• A-5. The automotive-plastic defect-detection proposal in the uploaded material describes a downstream application domain and is not part of terra-images' current or future delivery boundary; no camera, PLC, reject mechanism, or factory integration is in scope. Provenance: explicit scope boundary.
• A-6. Visual direction, palette, typography, and motion are supplied by the creative direction and are binding; unspecified implementation details are labeled defaults.

12. Glossary

• Dataset Owner — the sole active human persona; the practitioner who supplies labeled images and receives a trained model.
• Labeled image dataset — a collection of images together with their corresponding labels, supplied by the owner as training material.
• Requirement — a specific input the application needs from the owner before training can begin, shown on the Requirements page with an Action needed or Provided state.
• Training run — a single execution of model training on a dataset with a fixed set of supplied requirements; it has a status, timestamps, and either metrics and an artifact or a failure reason.
• Model — the trained image-labeling artifact produced by a completed training run, with its metrics, configuration, source dataset, and version identifier.
• Contact sheet — the halftone-treated grid of the owner's own image thumbnails with label tags, used as the product's signature imagery.
• Stamp / seal — the circular badge motif that marks the hero and reappears as the "model trained" seal on completed models.