TFJS Iris Workshop (Structured)

This workshop now uses:

• Zod for validated runtime configuration and payloads
• Winston for server-side logging
• Axios for HTTP calls (backend + frontend API client)
• fs-extra + csv-parse streaming to process dataset files efficiently
• SuperJSON for typed serialization of preprocess metadata
• Rolldown for Node compilation
• Vite + React 18 + TanStack Query for the UI
• Tailwind CSS v4 + DaisyUI v5 + PostCSS for styling
• Biome v2 for formatter-only workflow
• Optional @tensorflow/tfjs-node backend for faster training/inference in Node
• Compose includes under deploy/compose/*
• Multi-stage Docker targets under deploy/docker/*
• MinIO (S3-compatible) + init service for artifact storage bootstrap

Layout

• compose.yml: root compose using includes
• deploy/compose/app.yml: web + mlflow services
• deploy/compose/ops.yml: dataset + trainer + node-client + image-dataset + image-trainer
• deploy/compose/minio/*: minio service, init script, policy
• deploy/docker/Dockerfile: multi-stage targets (server, trainer, image-trainer, image-dataset, predict)
• src/*: backend, training, model IO, inference, config
• web/*: React app

Getting started (Baby mode 👶🍼)

This is a step-by-step recipe.
Think of it like building a toy castle: first floor, then walls, then roof 🏰

0) What you need first (the toy box) 🧰

• Docker + Docker Compose
• Node.js 20+
• just command runner

Check quickly:

docker --version
docker compose version
node --version
just --version

If one command fails, install that tool first.

1) Copy the environment file (give the app its name tag) 🏷️

cp .env.example .env

Why: .env contains ports and credentials used by MLflow + MinIO + app services.

2) Create local folders (make toy boxes for data/models) 📦

just init

Why: this creates shared/data, shared/model, shared/image-data, shared/image-model.

3) Build Docker images (cook the app containers) 🍳

just build

Why: builds all service images once so later commands are faster.

4) Run the classic Iris workshop (numbers in, species out) 🌼🔢

just workshop

What happens inside:

1. download Iris CSV
2. train numeric model (4 features → 3 species)
3. start web server

5) Open the app pages (peek inside) 👀

• MLflow: http://localhost:5000 (or your MLFLOW_PORT)
• Web UI: http://localhost:3000 (or your WEB_PORT)
• MinIO Console: http://localhost:9001 (or your MINIO_CONSOLE_PORT)

6) Run the image workshop (photo in, flower class out) 🖼️🌸

just workshop-image

What this does:

1. downloads public flower photos dataset
2. trains image model (5 classes)
3. starts web server with image endpoint ready

7) Try prediction from the browser 🧪

• Numeric tab: enter sepal/petal numbers, click Predict
• Image tab: upload flower photo, click Predict Image

If image model is not ready, the UI badge tells you.

8) Useful tiny commands (mini buttons) 🎮

just up              # start app stack
just dataset         # fetch iris CSV only
just train           # train numeric model only
just image-dataset   # fetch flower photos only
just image-train     # train image model only
just logs trainer    # watch trainer logs
just down            # stop everything

9) If something breaks (totally normal) 🩹

• Rebuild: just build
• Restart web: just web-up
• Clear image artifacts + dataset: just clean-image
• Clear numeric model artifacts: just clean-model

And yes, if your laptop fan sounds like a tiny helicopter 🚁, that means it is doing science. No panic. It is not trying to fly away (probably).

Notes

• trainer saves model files to shared/model/ and uploads copies to MinIO under runs/<runId>/model/.
• MLflow artifacts are configured to use s3://$S3_BUCKET via MinIO endpoint.
• Image upload prediction endpoint is POST /api/predict-image (multipart form field: image).
• Image model artifacts are saved in shared/image-model/ (model.json, weights.bin, image-meta.json).

MLflow chart tips (image training) 📈

• Use train_loss + val_loss (or train_accuracy + val_accuracy) for learning curves.
• For denser curves, use train_loss_batch + train_accuracy_batch (logged every 10 batches).
• Use final_validation_loss + final_validation_accuracy as one-point summary metrics after training.
• If a chart looks like a straight line, check run params first: epochs=1 means only one epoch point.
• On very slow machines, training may look "stuck" between epoch logs; native tfjs-node backend is auto-enabled when available.

Default image training params are tuned for workshop speed:

• IMAGE_SIZE=64
• IMAGE_MAX_SAMPLES_PER_CLASS=80
• IMAGE_EPOCHS=8

Public image dataset source

• TensorFlow tf_flowers dataset (3,670 training images, 5 classes):
  dandelion, daisy, tulips, sunflowers, roses
• Download URL used by this project:
  https://storage.googleapis.com/download.tensorflow.org/example_images/flower_photos.tgz
• Reference:
  • https://github.com/tensorflow/datasets/blob/master/docs/catalog/tf_flowers.md
  • https://github.com/tensorflow/datasets/blob/master/tensorflow_datasets/datasets/tf_flowers/tf_flowers_dataset_builder.py