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.