koszewscy/azure-image-chooser
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Migrated to NodeJS/Vite/Express/Material UI 2 #1

Merged
slawek merged 15 commits from feature/migration-to-nodejs into main 2026-04-20 08:04:33 +02:00
Conversation 0 Commits 15 Files Changed 42 -160
5 changed files with 0 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 055f51aa55 - Show all commits

0
Dockerfile → app-new/Dockerfile
View File

0
entrypoint.sh → app-new/entrypoint.sh
View File

0
healthcheck.js → app-new/healthcheck.js
View File

103
migration-plan/plan.md
View File

@@ -1,103 +0,0 @@
## Plan: React + Vite Rewrite of Azure Image Chooser
Rewrite the current Streamlit application into a two-tier web app (React + Vite frontend and Node.js backend) while preserving core image-discovery behavior (location -> publisher -> offer -> SKU -> version) and generated usage outputs, and redesigning UX and template architecture, with strict non-destructive workspace constraints.
**Hard constraints**
1. Existing workspace files must remain untouched, except .gitignore.
2. All new application source must live under src/.
3. Build artifacts must be emitted only to dist/.
4. A new Dockerfile and entrypoint.sh must be added at the workspace root.
5. The container runtime must use Node.js 24 LTS on Debian trixie-slim (node:24-trixie-slim).
6. All new source code must be TypeScript and use the TypeScript 6 transpiler (latest revision).
7. Frontend UI must use plain Material UI v9.x.x.
8. All MUI-related questions and implementation decisions must be resolved using mui-mcp as the primary source/tool.
9. Frontend must use the latest stable React line (React 19.2.x), with no legacy compatibility or migration work included.
10. Docker is not available in the target environment; container lifecycle operations must use Apple-sponsored container CLI only.
**Steps**
1. Phase 0 - Planning artifact handoff
1. After plan mode is turned off, copy plan artifacts to workspace directory migration-plan/ for future reference:
- migration-plan/plan.md
- migration-plan/version-manifest.md
2. Keep session/repo memory files as source-of-truth backups.
1. Phase 1 - Baseline and migration contract
1. Capture current functional contract from existing app behavior in app/image-chooser.py: cascading selectors, semantic version sorting, empty-state behavior, and SKU export format.
2. Define backend API contract for frontend consumption: locations, publishers, offers, skus, versions, templates, rendered output, and SKU export endpoints, including error payloads.
3. Lock frontend framework prerequisites from current MUI status before scaffolding: Material UI v9.x.x, React 19.2.x (latest stable), Emotion styling engine defaults, and required companion packages.
4. Explicitly exclude legacy React compatibility paths and migration workarounds from scope (no legacy shims, no backward-compat migration tracks).
5. Define target repository layout under src/ for frontend and backend packages, with dist/ as the fixed artifact directory.
6. Define non-destructive execution guardrails: no edits to legacy files except .gitignore updates for node_modules and artifact outputs.
1. Phase 2 - Node backend in src
1. Scaffold backend under src/backend in TypeScript (mandatory) with modules for Azure compute discovery, template catalog, rendering, and validation, compiled with TypeScript 6.
2. Implement Azure integration equivalent to current data loaders, including region_type=Physical filtering and conditional semantic version sorting when all versions match X.Y.Z.
3. Implement endpoint caching (TTL by endpoint+params) and structured logging.
4. Implement redesigned template subsystem with metadata model and render endpoint.
5. Add backend tests under src/backend aligned to the API contract.
1. Phase 3 - React + Vite frontend in src
1. Scaffold frontend under src/frontend using Vite with TypeScript (mandatory), configure output directory to dist/, compile with TypeScript 6, use React 19.2.x (latest stable), and use plain Material UI v9.x.x as the UI component library.
2. Build cascading async selectors with deterministic reset behavior (location -> publisher -> offer -> sku -> version).
3. Implement API-driven state management (for example TanStack Query) with loading, empty, and error states.
4. Implement usage output UI with template selection, rendered snippet display, copy action, and SKU export display, using plain Material UI v9.x.x components and styling primitives (Emotion-based engine).
5. Add frontend tests under src/frontend for cascade behavior and output rendering.
1. Phase 4 - Root runtime wrapper and cutover
1. Add new root Dockerfile that builds/runs the new src-based application stack on Node.js 24 LTS with Debian trixie-slim (node:24-trixie-slim), and ensure runtime commands are documented/executed via Apple container CLI (not Docker).
2. Add new root entrypoint.sh that starts the new runtime components.
3. Update .gitignore for node_modules, dist artifacts, and any new temporary outputs.
4. Validate core behavior parity against Streamlit baseline using representative selections and generated outputs.
5. Keep legacy assets in place (untouched) during and after migration unless separately approved for cleanup.
**Parallelism and dependencies**
1. Phase 0 runs first and gates execution handoff artifacts in workspace.
2. Phase 1 blocks implementation.
3. After API contract freeze, backend (Phase 2) and frontend scaffold (Phase 3) can run in parallel.
4. Phase 4 depends on stable frontend/backend run commands and artifact paths.
**Relevant files**
- /Users/slawek/src/azure-image-chooser/app/image-chooser.py - source-of-truth behavior reference only; do not modify.
- /Users/slawek/src/azure-image-chooser/app/templates.json - current template catalog reference only; do not modify.
- /Users/slawek/src/azure-image-chooser/app/templates/arm_vm.jsonc - output reference only; do not modify.
- /Users/slawek/src/azure-image-chooser/app/templates/azurerm_hcl.tpl - output reference only; do not modify.
- /Users/slawek/src/azure-image-chooser/app/templates/shell.tpl - output reference only; do not modify.
- /Users/slawek/src/azure-image-chooser/.gitignore - only existing file allowed to be changed.
- /Users/slawek/src/azure-image-chooser/src/ - new source tree for rewritten application.
- /Users/slawek/src/azure-image-chooser/dist/ - artifact output directory.
- /Users/slawek/src/azure-image-chooser/Dockerfile - new root runtime image definition.
- /Users/slawek/src/azure-image-chooser/entrypoint.sh - new root runtime entrypoint.
**Verification**
1. Workspace contains migration-plan/plan.md and migration-plan/version-manifest.md after plan mode is off.
2. Git diff check confirms only new files plus .gitignore modifications; no edits in legacy files.
3. Backend tests pass for API contract, validation, filtering, sorting, and rendering.
4. Type-check/transpile verification passes with TypeScript 6 for both backend and frontend packages.
5. Frontend tests pass for selector cascade and output rendering.
6. Frontend dependency and implementation checks confirm plain Material UI v9.x.x is used (no alternate UI framework).
7. Verification confirms MUI installation prerequisites are met for React 19.2.x and Emotion packages.
8. Verification confirms there are no legacy compatibility layers or migration-specific workarounds in frontend dependencies/configuration.
9. Local run verifies UI flow and generated outputs match baseline behavior for representative scenarios.
10. Image build inspection via Apple container CLI confirms the runtime base image is Node.js 24 LTS on Debian trixie-slim (node:24-trixie-slim).
11. Artifact generation confirms outputs land only in dist/ directory.
**Decisions**
- Use Node.js backend (confirmed).
- Keep only core functionality unchanged; UX and architecture can be redesigned (confirmed).
- Redesign template system now (confirmed).
- Enforce non-destructive migration: existing files untouched except .gitignore (confirmed).
- Place all new application code in src/ and add new root Dockerfile + entrypoint.sh (confirmed).
- Use Node.js 24 LTS on Debian trixie-slim as container runtime base image (confirmed).
- Use TypeScript-only source with TypeScript 6 transpiler across backend and frontend (confirmed).
- Use plain Material UI v9.x.x for frontend UI implementation (confirmed).
- Use mui-mcp as the primary tool/source for all MUI-related implementation questions (confirmed).
- Use latest stable React (19.2.x at planning time) and exclude legacy compatibility/migration paths (confirmed).
- Use Apple container CLI (macOS 26, Apple silicon) for container operations; no Docker dependency (confirmed).
**Scope boundaries**
- In scope: functional core parity for image lookup and output generation, new frontend/backend architecture in src/, root runtime wrappers, and .gitignore updates.
- Out of scope: modifying existing legacy app/ and terraform/ files, removing legacy code, or altering old deployment definitions.
**Further Considerations**
1. Artifact output is fixed to dist/ for consistency with the chosen convention.
2. If backend and frontend are separate runtime processes, define entrypoint process model early (single-process with static serve vs process manager).

57
migration-plan/version-manifest.md
View File

@@ -1,57 +0,0 @@
## Version Manifest: React + Vite + MUI Rewrite
### Environment and container tooling
- macOS: 26 (host requirement)
- Container CLI: apple/container (latest release observed: 0.11.0)
- Container runtime command: container (Docker unavailable by constraint)
- Base image: node:24-trixie-slim (Node 24 LTS on Debian trixie-slim; OCI-compatible)
### Frontend stack
- Node.js runtime: 24.x LTS
- React: 19.2.5
- React DOM: 19.2.5
- TypeScript: 6.0.3
- Vite: 8.0.8
- @vitejs/plugin-react: 6.0.1
- @types/react: 19.2.14
- @types/react-dom: 19.2.3
- Material UI core: @mui/material 9.0.0
- Material UI styling engine: @emotion/react 11.14.0, @emotion/styled 11.14.1
- Optional state-fetching utility selected in plan: @tanstack/react-query 5.99.2
### Backend stack (planned)
- Node.js runtime: 24.x LTS
- Express: 5.2.1
- Zod: 4.3.6
- TypeScript: 6.0.3
### MUI knowledge/tooling
- MUI docs index for LLM consumption: https://mui.com/material-ui/llms.txt
- MUI MCP package invocation model: npx -y @mui/mcp@latest
## Compatibility Audit
### Hard compatibility checks
1. Node 24 vs Vite 8: compatible (Vite requires Node 20.19+ or 22.12+).
2. React 19.2.x vs MUI 9: compatible (MUI supports React ^17 || ^18 || ^19).
3. React 19.2.x vs react-dom 19.2.5: compatible (same major/minor line).
4. TypeScript 6 vs MUI 9: compatible (MUI requires TS >=4.9).
5. Node 24 vs Express 5.2.1: compatible (Express requires Node >=18).
6. Apple container vs Dockerfile workflow: compatible (container build supports Dockerfile and Containerfile).
### Environment-specific incompatibilities / risks
1. Docker command compatibility: incompatible by environment constraint.
- Any script that assumes docker build/run must be translated to container build/run.
2. Apple container stability: medium risk.
- Project is pre-1.0 and may introduce breaking changes in minor releases.
- Mitigation: pin CLI release during execution and document upgrade policy.
3. Slim Debian runtime package availability: low-to-medium operational risk.
- trixie-slim is smaller than full images and may omit convenience packages.
- Mitigation: install only required OS packages explicitly and validate build/runtime dependencies.
4. @mui/mcp@latest floating version: reproducibility risk.
- Mitigation: pin exact MCP package version for CI/repeatable local behavior once selected.
### Migration-policy compatibility with user constraints
1. Latest stable React only: satisfied by React 19.2.x.
2. No legacy/migration support tracks: satisfied; no React 18 fallback assumptions included.
3. MUI usage policy: satisfied with plain Material UI v9.x.x and mui-mcp-first guidance.