builderflow.md

Commit-1

ReactFast Project Overview

A minimal full-stack setup with a FastAPI backend serving a Vite + React frontend. The frontend builds into frontend/dist, and FastAPI mounts it under the /app route.

What this project includes

• Backend: FastAPI app (backend/app.py) mounting static files from the React build.
• Frontend: Vite + React (TypeScript) app configured with base /app/ so assets resolve when hosted under that path.
• Local dev: Build frontend once, then run the FastAPI server. Visit http://127.0.0.1:<port>/app/.

Dependencies

• Python (backend)
  • fastapi: Web framework serving API and static files
  • uvicorn: ASGI server to run the FastAPI app
• Node (frontend)
  • react, react-dom: UI library and DOM renderer
  • vite: Build tool and dev server
  • @vitejs/plugin-react: React plugin for Vite (Fast Refresh, JSX, etc.)
  • typescript, @types/react, @types/react-dom: TypeScript and React typings

---

Folder tree and file descriptions

backend/

backend/
├─ app.py                  # FastAPI app mounting the React build at /app
├─ requirements.txt        # Python dependencies for backend (fastapi, uvicorn)
├─ __pycache__/            # Python bytecode cache (auto-generated)
└─ .venv/                  # Local Python virtual environment (developer local)

frontend/

frontend/
├─ index.html              # Vite HTML entry; loads /src/main.tsx
├─ package.json            # Frontend scripts and dependencies
├─ package-lock.json       # Exact dependency versions (npm lockfile)
├─ tsconfig.json           # TypeScript compiler options for the app
├─ vite.config.ts          # Vite config; base set to /app and outDir=dist
├─ src/                    # Application source code
│  ├─ App.tsx              # Main UI component rendered by the app
│  ├─ main.tsx             # React entry; creates root and renders <App />
│  └─ style.css            # Minimal global styles
├─ dist/                   # Production build output (generated by `npm run build`)
│  ├─ index.html           # Built HTML referencing hashed asset files under /app
│  └─ assets/              # Hashed JS/CSS bundles and sourcemaps
│     ├─ index-*.js        # Production JS bundle (hashed filename)
│     ├─ index-*.js.map    # Sourcemap for debugging (if enabled)
│     └─ index-*.css       # Production CSS bundle (hashed filename)
└─ node_modules/           # Installed frontend dependencies (generated by npm)

---

How it works

1. Build the frontend (Vite) which outputs to frontend/dist with asset URLs prefixed by /app/.
2. Start the FastAPI server; it mounts frontend/dist as static files at the /app route.
3. Navigate to http://127.0.0.1:<port>/app/ to view the app (index.html + assets).

Common commands (optional)

• Build frontend: npm run build in frontend/
• Run backend: uvicorn app:app --host 127.0.0.1 --port 8000 in backend/ (after installing requirements)

Notes

• If you change the frontend base path or output folder, update either Vite’s base/build.outDir or the backend static mount path accordingly.
• dist/ is generated—do not edit files there manually; edit files under src/ instead and rebuild.

---

Commit-2

High-level summary of enabling frontend ↔ backend communication.

• Backend

  • Added a simple POST API at /api/transform that accepts { text: string } and returns { result: string } with a minimal transformation.
  • Kept the React static site mounted at /app so built assets resolve correctly (aligned with Vite base: '/app/').

• Frontend

  • Updated the main UI (src/App.tsx) to include:
    • A label, a textbox for user input, and a submit button.
    • On submit, a fetch('/api/transform', { method: 'POST', body: JSON.stringify({ text }) }) call.
    • Displays the returned result string below the form.
  • Light, elegant styling in src/style.css to keep the layout centered and readable without overengineering.

• Result

  • Users can type a message, submit, and see a transformed response from the FastAPI backend—served together under the same origin, avoiding CORS configuration.

---

Commit-3

High-level summary of adding containerization (Docker) support.

• Purpose

  • Provide a reproducible build artifact bundling backend (FastAPI) and pre-built frontend (Vite) into one image.
  • Simplify deployment: single docker run serves both API and static UI.

• Dockerfile Structure (multi-stage)

  • Stage 1 (node:20-alpine): installs frontend deps and runs npm run build to produce dist/.
  • Stage 2 (python:3.12-slim): installs backend Python deps, copies backend code and built frontend/dist.
  • Starts with: uvicorn backend.app:app --host 0.0.0.0 --port 8000.

• Key Paths Inside Image

  • /app/backend – FastAPI code
  • /app/frontend/dist – Built static assets served by FastAPI at /app route

• Added Files

  • Dockerfile – Multi-stage build definition
  • .dockerignore – Excludes node_modules, virtual envs, caches, VCS metadata, logs, etc., reducing context size and image bloat

• Build & Run (local)

  1. Build image:
     • docker build -t reactfast .
  2. Run container:
     • docker run --rm -p 8000:8000 reactfast
  3. Access UI:
     • http://localhost:8000/app/

• Customization Notes

  • To enable auto-reload in development, run locally without Docker or create a dev Dockerfile variant mounting source.
  • For production scaling, consider adding a process manager (e.g., gunicorn with uvicorn.workers.UvicornWorker) and HEALTHCHECK.
  • Pin dependency versions more strictly if reproducibility across time is critical.

• Outcome

  • Project can be built and deployed as a single immutable image; frontend and backend remain in sync at build time.

• Pushing the app to Azure Container Registry. Use below commands

  • docker login to login to Azure Container Registry
  • docker tag <app_name>:latest <registry-name>.azurecr.io/<app_name>:latest
  • docker push <registry-name>.azurecr.io/<app_name>:latest

  Commit-4

  High-level summary of adding CI automation (GitHub Actions) to build and push the Docker image to Azure Container Registry (ACR).

  • Purpose

    • Automate image builds on each push to main (and manual dispatch) ensuring the registry always has an up‑to‑date image.
    • Provide traceable image tags (<commit-sha> and latest) for rollback and promotion.

  • Secrets / Inputs

    • AZURE_CREDENTIALS: JSON from az ad sp create-for-rbac --role AcrPush --scopes <ACR_ID> --sdk-auth.
    • ACR_LOGIN_SERVER: e.g. minimum.azurecr.io.
    • (Optional) ACR_NAME if deriving login server dynamically.

  • Workflow Steps (simplified)

    1. Checkout repository source.
    2. Azure login using service principal (azure/login).
    3. Authenticate to ACR (either via az acr login or docker/login-action).
    4. Build Docker image with existing multi-stage Dockerfile.
    5. Tag image twice: :<git-sha> and :latest.
    6. Push both tags to ACR.
    7. Summarize pushed tags for visibility.

  • Tagging Strategy

    • Immutable: registry/app:{{ github.sha }} for precise traceability.
    • Mutable convenience: registry/app:latest for default deployments / quick tests.

  • Minimal Example (conceptual)

    • Trigger: on: push: branches: [ main ] + workflow_dispatch.
    • Uses official actions: actions/checkout, azure/login, docker/build-push-action.

  • Benefits

    • Eliminates manual local build/push steps.
    • Reduces risk of “works on my machine” discrepancies.
    • Provides consistent, auditable artifact generation tied to commit history.

  • Follow-on Opportunities

    • Add deploy job (e.g., to Azure Web App / Container Apps / AKS) after successful push.
    • Introduce image security scanning (Trivy / Microsoft Defender).
    • Add build cache (GitHub Actions cache or ACR build tasks) for faster builds.
    • Add semantic version tagging (e.g., v1.2.3) if release process formalizes.

  • Outcome

    • CI pipeline ensures every code change can rapidly produce a runnable, versioned container image in ACR, ready for deployment workflows.