A real discovery, start to finish

Product Requirements Document: React Hello world

Document Version: 1.0 Date: 2026-07-11 Status: Draft for Review

1. Executive Summary

React Hello world is a lightweight, beginner-friendly React + TypeScript starter application designed to serve as a teaching tool for individuals and teams learning React fundamentals. Unlike a bare-bones “Hello World” template, React Hello world combines a working, well-structured codebase with a curated set of guided learning exercises, giving mentors a repeatable way to onboard mentees into real-world React development practices.

The product consists of two tightly coupled deliverables:

1. The Starter Application — a small, playful, brightly-colored React + TypeScript app featuring a friendly landing page, client-side routing (2+ routes), a basic API data-fetching example, and a mobile-responsive layout — all built with standard, unopinionated tooling (no custom component libraries or non-standard conventions).
2. The README-Based Learning Path — a documentation layer containing 2-3 structured challenges/exercises (e.g., “add a new page and route,” “set up one-command local development,” “fetch and display data from a new endpoint”) that mentees complete to build muscle memory that transfers directly to day-job React work.

The product’s success is not measured by downloads or stars, but by whether the people who clone it — the author’s colleagues and mentees — become measurably more confident and competent at React tasks in their actual jobs. The feedback loop (code review) is intentionally external to the product; React Hello world’s job is to provide the sandbox and the structured prompts, not the grading.

2. Problem Statement

Learning React by reading documentation alone is slow and disconnected from real work. Many existing “Hello World” boilerplates solve the wrong problem: they get code running but teach almost nothing about the concepts that actually trip up beginners on the job — routing, component composition, styling, and connecting to external data.

At the same time, fully-featured production boilerplates (with auth, state management libraries, design systems, CI/CD, etc.) overwhelm beginners with decisions and plumbing that obscure the fundamentals rather than illuminate them.

There is a gap between:

• Too simple — a single-file “Hello World” that teaches nothing transferable.
• Too complex — a production-grade template that buries fundamentals under abstraction and tooling.

React Hello world fills this gap: a small, clean, well-organized starter that touches every core React concept a beginner needs (components, routing, styling, data fetching) — paired with hands-on exercises that turn passive cloning into active learning, so the skills gained transfer directly to real workplace React codebases.

3. Target Users & Personas

Persona 1: “The Mentor” (Primary Author/Owner)

• A developer who works with junior or transitioning engineers and wants a reusable, low-maintenance tool to kickstart their learning.
• Values clarity and standard conventions over cleverness — wants mentees to transfer skills to real work, not learn quirky patterns.
• Will use this repeatedly across multiple mentees/teams, so it needs to be self-explanatory with minimal hand-holding required.

Persona 2: “The Beginner Mentee”

• Has some general programming knowledge but is new to React and/or the React + TypeScript stack.
• Is not necessarily new to coding, but is new to this specific ecosystem (JSX, component model, client-side routing, TypeScript typing for React).
• Learns best by doing — needs a working example to explore, break, and rebuild rather than a wall of documentation.
• Will have their work reviewed by someone else (the Mentor or a peer) — the product does not need to grade them itself.

Persona 3: “The Returning Learner” (secondary)

• Someone who has cloned this starter before (or a similar one) and wants a quick refresher before jumping into a work-related React repo.
• Prioritizes speed of setup and a quick reminder of core patterns over deep guidance.

4. User Stories & Requirements

Core Setup & Onboarding

• As a mentee, I want to clone the repo and get it running with a single command, so I don’t waste time on environment setup.
• As a mentor, I want the README to clearly explain prerequisites (Node version, package manager) so mentees don’t get stuck before they even start.

Landing Page & Visual Design

• As a mentee, I want to see a friendly, colorful landing page immediately after starting the app, so I feel welcomed and motivated rather than intimidated.
• As a mentor, I want the color scheme and layout to feel intentional and polished (not default/unstyled), so the project reflects care and craft.
• As a mentee, I want the layout to work well on my phone or tablet, so I can explore the app regardless of device.

Routing & Navigation

• As a mentee, I want to see at least two distinct pages/routes connected via navigation, so I understand how client-side routing works in practice.
• As a mentee, I want a guided exercise that asks me to add a new page and route myself, so I can practice this concept hands-on rather than just reading about it.

Component Structure

• As a mentee, I want the codebase organized into clear, small, well-named components, so I can see how a React app is composed rather than one giant file.
• As a mentor, I want consistent, standard file/folder conventions, so mentees transfer this structure knowledge to typical workplace repos.

Styling

• As a mentee, I want to see how the color scheme and styles are applied (e.g., via CSS or CSS modules), so I understand a standard styling approach without a custom design system getting in the way.
• As a mentee, I want a guided exercise that invites me to tweak a color or style, so I build confidence making safe, visible changes.

Data Fetching (API Integration)

• As a mentee, I want to see a simple example of fetching data from an external or mock API and rendering it, so I understand a fundamental real-world React pattern.
• As a mentor, I want this data-fetching example to be simple and dependency-light, so it doesn’t distract from the core teaching goal.

TypeScript

• As a mentee, I want to see TypeScript used in a straightforward, non-overwhelming way (basic prop types, simple interfaces), so I get exposure to typed React without steep complexity.

Learning Exercises (README)

• As a mentee, I want 2-3 clearly described challenges in the README, each with a concrete, self-checking outcome (e.g., “you’ll know it worked when you see a new page at /about”), so I know what “done” looks like without needing an automated grader.
• As a mentor, I want one of the challenges to be the one-command local setup/deployment task itself, so mentees also practice tooling fundamentals, not just React code.
• As a mentee, I want the exercises to mirror real workplace tasks (adding a page, wiring a route, fetching data), so my practice directly transfers to my day job.

5. Feature Specifications (Prioritized)

P0 — Must Have (Core Deliverable)

5.1 Project Scaffold (React + TypeScript)

• Built with a standard, widely-recognized tool (e.g., Vite) using the React + TypeScript template — no custom/non-standard build tooling.
• Standard folder structure: src/components, src/pages (or src/routes), src/styles, src/api (or similar), clearly named and documented in the README.
• One-command install and run (e.g., npm install && npm run dev).

5.2 Friendly, Colorful Landing Page

• A welcoming home page with a headline, short friendly copy, and visual elements that reflect a “playful and welcoming” tone.
• A cohesive, intentional color palette (bright, friendly, approachable) applied consistently across the app — defined in a single, easy-to-find location (e.g., CSS variables/theme file) so it’s simple for a beginner to tweak.

5.3 Client-Side Routing (2+ Routes)

• Standard routing library (e.g., React Router) implementing at least two pages (e.g., Home and About), with simple navigation (e.g., a nav bar).
• Routing setup kept simple and readable — no nested/advanced routing patterns that would obscure the basics.

5.4 Component Composition

• The app is broken into a small number of clear, reusable components (e.g., Header, Footer, Card, Layout) to demonstrate composition and props passing, including basic TypeScript prop typing.

5.5 Basic Styling Approach

• A single, standard styling method used consistently (plain CSS or CSS Modules) — no CSS-in-JS libraries or design systems that add conceptual overhead.
• Clear demonstration of how the color scheme flows from a central definition into components.

5.6 Simple API Data-Fetching Example

• One page/component that fetches data from a public or mock API (e.g., a free public API or a local JSON/mock server) and renders it, using basic useEffect/fetch (or an equivalently simple approach).
• Includes basic loading and error states to illustrate real-world data-fetching concerns without overengineering.

5.7 Mobile-Responsive Layout

• Layout and navigation adapt cleanly to small screens (responsive CSS — flexbox/grid and media queries or an equivalent standard approach).
• No native mobile (React Native) target in this version — responsive web only.

5.8 README with Guided Learning Exercises

• Clear “Getting Started” section (prerequisites, install, run commands).
• Explanation of project structure and where to find key concepts (routing, components, styling, data fetching).
• 2-3 structured challenges, each including:
  1. Goal — what to build/change.
  2. Why it matters — the real-world skill it mirrors.
  3. Definition of “it worked” — a concrete, observable outcome (e.g., “navigating to /about shows your new page and the nav updates”).
• Suggested challenges:
  • Add a new page and corresponding route (with nav link).
  • Set up and document a one-command local dev/deploy workflow (if not already fully covered in setup).
  • Modify the color scheme/theme and confirm it propagates across all components.
• Explicit note that code review by a mentor/peer is the intended feedback loop — the README should encourage learners to share their branch/PR for review rather than expecting the app itself to validate correctness.

P1 — Should Have (Strengthens Teaching Value)

5.9 Theming/Color Palette Documentation

• A short section in the README (or a THEME.md) explaining the color palette choices and where to change them, reinforcing the styling exercise.

5.10 Basic Linting/Formatting Setup

• Standard ESLint + Prettier configuration out of the box, so learners are exposed to common workplace tooling conventions without needing to configure it themselves.

5.11 Simple Navigation Component

• A shared NavBar component used across pages, demonstrating shared layout and active-link styling — a natural extension point for the “add a page” exercise.

P2 — Nice to Have (Future Polish)

5.12 Deployment Guide

• Optional README section pointing to a simple static hosting option (e.g., Vercel/Netlify/GitHub Pages) for learners who want a hosted preview, tied to the “one-command setup” exercise.

5.13 Sample Solution Branch

• An optional solutions branch or tag showing one possible completed version of each challenge, for mentors who want to offer a reference without putting it in the main README (kept separate to preserve the self-directed learning experience).

5.14 Dark/Light Theme Toggle

• A simple theme-switch feature reinforcing the styling/theming concepts, if scope allows.

6. User Flows & Journeys

Flow 1: First-Time Setup

1. Mentee receives repo link from Mentor.
2. Mentee clones the repository.
3. Mentee reads the README “Getting Started” section.
4. Mentee runs the one-command install/start.
5. Mentee sees the colorful landing page running locally in the browser.
6. Mentee clicks through the existing routes/nav to explore the app.

Flow 2: Exploring the Codebase

1. Mentee opens the project in their editor.
2. Mentee reviews the folder structure guide in the README.
3. Mentee inspects pages/components/styles to see how the landing page, routing, and colors are implemented.
4. Mentee inspects the data-fetching component to see the API integration pattern.

Flow 3: Completing a Learning Challenge (e.g., “Add a New Page”)

1. Mentee reads the challenge description and “definition of success” in the README.
2. Mentee creates a new page/component file.
3. Mentee adds a new route and nav link.
4. Mentee runs the app locally and confirms the new page renders and navigation works.
5. Mentee commits changes and shares the branch/PR with their Mentor for code review (external to the product).

Flow 4: Styling Exploration Challenge

1. Mentee locates the central color/theme definition.
2. Mentee changes one or more color values.
3. Mentee confirms the change is reflected consistently across the landing page and other routes.
4. Mentee reflects (optionally documents) what they changed and why.

Flow 5: One-Command Setup/Deploy Challenge

1. Mentee reviews the current run/setup process.
2. Mentee is challenged to document or streamline it into a single command (if not already fully in place) or to deploy it to a simple hosting provider.
3. Mentee validates by tearing down and re-running the setup from scratch (or sharing a live preview link).

7. Success Metrics & KPIs

Since this is a teaching tool rather than a commercial product, success is primarily qualitative and observed indirectly through mentee outcomes. Relevant indicators include:

• Setup success rate: Percentage of mentees who get the app running locally without needing direct help from the Mentor (target: near 100%, given “beginner-friendly” is a core requirement).
• Challenge completion rate: Percentage of mentees who complete at least 2 of the 3 README challenges independently.
• Time-to-first-success: Time from clone to seeing the running landing page (should be minutes, not hours).
• Transfer of skill (primary, long-term signal): Mentor’s qualitative observation that mentees demonstrate improved confidence/competence on React tasks (routing, components, data fetching, styling) in their actual day-job codebase — assessed informally via code review, not tracked by the product itself.
• Reusability: The Mentor is able to reuse the same starter across multiple mentees/cohorts without modifying the core app or README each time.
• Low support burden: Minimal back-and-forth needed from the Mentor to unblock a mentee during setup or the challenges (a sign the README is self-sufficient).

Explicitly out of scope for metrics: analytics, telemetry, or in-app tracking of any kind — this is a local learning tool, and success is judged through human code review, not product instrumentation.

8. Acceptance Criteria

The product is considered complete and ready for use when all of the following are true:

Setup & Tooling

• [ ] Repository can be cloned and run locally with a single documented command (or a documented two-step install+run).
• [ ] Project uses React + TypeScript with a standard, widely-adopted scaffolding tool.
• [ ] No non-standard tooling, custom component libraries, or unconventional repo structures are introduced.

Landing Page & Styling

• [ ] App displays a friendly, welcoming landing page on load.
• [ ] A bright, playful, cohesive color palette is applied consistently across all pages/components.
• [ ] Color values are defined in a single, clearly identifiable location that a beginner can find and edit.

Routing

• [ ] App includes at least two distinct routes/pages, connected via a visible navigation element.
• [ ] Routing is implemented with a standard routing library in a simple, readable way.

Components

• [ ] App is composed of multiple clear, reasonably small components (not a single monolithic file).
• [ ] At least one component demonstrates props with basic TypeScript typing.

Data Fetching

• [ ] At least one page/component fetches data from an external or mock API and renders the result.
• [ ] Loading and error states are visibly handled, even if simply implemented.

Responsiveness

• [ ] Layout adapts cleanly to mobile-sized viewports without broken navigation or overflow issues.

README & Learning Exercises

• [ ] README includes clear prerequisites and setup instructions.
• [ ] README explains the project structure and where core concepts (routing, components, styling, data fetching) live.
• [ ] README includes 2-3 challenges, each with a goal, rationale, and a concrete definition of success.
• [ ] One challenge addresses adding a new page/route; one challenge addresses styling/color changes; one challenge addresses setup/tooling (e.g., one-command run or simple deployment).
• [ ] README explicitly notes that code review (external to the app) is the intended feedback mechanism for verifying learning outcomes.

9. Out of Scope / Future Considerations

Explicitly out of scope for this version:

• Authentication or login flows of any kind (deemed too advanced for this starter’s teaching goals).
• Native mobile targets (e.g., React Native) — the app will be responsive web only.
• State management libraries (e.g., Redux, Zustand) beyond React’s built-in state/hooks — not mentioned as a requirement and would add complexity beyond the agreed scope.
• Automated grading, in-app progress tracking, or telemetry — the feedback loop is intentionally human (code review), not built into the product.
• Custom design systems or third-party component libraries — the project intentionally uses standard, minimal tooling to keep focus on fundamentals.
• CI/CD pipelines beyond a simple, optional deployment guide.

Potential future considerations (not committed for this version):

• A solutions branch/tag with reference implementations of each challenge for mentors.
• Additional/optional challenges covering forms, basic state management, or simple testing (e.g., a “write your first test” exercise), if the teaching scope is expanded later.
• A dark/light theme toggle as an extended styling exercise.
• An expanded set of mock API endpoints to support more advanced data-fetching exercises (e.g., search, pagination).
• Versioned or tiered challenge tracks (beginner vs. intermediate) if the tool is used across a wider range of skill levels.
• A lightweight companion guide for Mentors on how to run this as a structured onboarding session (timing, expectations, review checklist).

Technical Architecture Document: React Hello world

Project: React Hello world Document Date: 2026-07-11 Version: 1.0 Status: Draft for Implementation

1. Architecture Overview

React Hello world is a teaching-first starter kit, not a production product. Its primary “customer” is a mentee who clones the repository, runs it, reads a small number of guided README challenges, and comes away with hands-on practice in the React concepts that matter most on the job: component composition, client-side routing, styling architecture, and consuming a backend API.

Because the exercises are the product, the architecture is deliberately kept small, conventional, and transparent — every layer should be easy to read end-to-end in one sitting. At the same time, the discovery conversation surfaced a real requirement: this should reflect actual day-job patterns, not a toy. That means:

• A genuine frontend/backend split (SPA + REST API), even if the backend is intentionally lightweight.
• TypeScript throughout, matching modern professional React codebases.
• Mobile-responsive layout, not just desktop.
• A “one-command” local developer experience, which is itself framed as a learning exercise.
• No authentication — explicitly descoped to avoid overwhelming beginners with session/token complexity.

High-level shape:

• Frontend: A Vite + React + TypeScript single-page application with React Router (2–3 routes), a bright/playful CSS theme built on CSS custom properties, and a responsive layout.
• Backend: A minimal Express + TypeScript API serving a small “Greetings” dataset from in-memory storage — enough to demonstrate fetch, loading/error states, and typed API contracts, without the overhead of a real database.
• Repository shape: An npm-workspaces monorepo (apps/web, apps/api) with a root-level script that starts both services together — the “one-command setup” that doubles as a guided exercise.
• Documentation layer: A README containing setup instructions and 2–3 self-checking challenges (e.g., add a new route/page, add a new greeting end-to-end, get the one-command dev environment running). The README is the pedagogical core of the project; the code is the sandbox.

The architecture optimizes for clarity over cleverness: no state management library, no CSS framework abstraction layer, no server-side rendering, no auth — just the essential plumbing a professional React app has, explained well.

2. Technology Stack (with rationale)

3. System Architecture Diagram

flowchart TB
    Learner[/Learner's Browser/] -->|HTTPS| Web[React SPA - Vite Build]
    Web -->|React Router| Home[Home Route]
    Web -->|React Router| Greetings[Greetings Route]
    Web -->|React Router| About[About Route]
    Greetings -->|fetch JSON, HTTPS| API[Express API Service]
    API --> Store[(In-Memory Greetings Store)]
    API --> Health{Health Check}
    DevScript[Root npm run dev] -->|starts| Web
    DevScript -->|starts| API
    CI[GitHub Actions CI] -->|lint/test/build| Repo[(Git Repository)]
    Repo -->|deploy| Web
    Repo -->|deploy| API

Flow summary: The learner’s browser loads the static SPA (built by Vite, served via CDN in production or Vite’s dev server locally). React Router resolves one of the SPA’s client-side routes. The Greetings route calls the Express API over HTTPS to fetch the greetings dataset, which is held in a simple in-memory store on the server. A root-level dev script starts both services together locally; CI validates the code on every push, and each service deploys independently to its own hosting target.

3.1 Request Sequence: Fetching Greetings

sequenceDiagram
    participant U as Learner (Browser)
    participant R as React Router
    participant C as GreetingsPage Component
    participant H as useGreetings Hook
    participant A as Express API
    participant S as In-Memory Store

    U->>R: Navigate to /greetings
    R->>C: Render GreetingsPage
    C->>H: Call useGreetings()
    H->>A: GET /api/greetings
    A->>S: Read greetings array
    S-->>A: Greeting[]
    A-->>H: 200 OK + JSON body
    H-->>C: { data, loading:false, error:null }
    C-->>U: Render colourful greeting cards

4. Data Models & Database Design

There is no traditional database in this starter — that is an intentional teaching decision to remove setup friction. Instead, a single, simple domain entity is modeled and served from memory, which is sufficient to teach real fetch/response/typing patterns.

4.1 Entity: Greeting

interface Greeting {
  id: string;        // stable identifier, e.g. "en-01"
  language: string;  // e.g. "English"
  message: string;   // e.g. "Hello, world!"
  flagEmoji: string; // e.g. "🇬🇧" – used for the playful UI
  colorAccent: string; // hex value used to theme the greeting card
}

Seed data ships with ~8–10 greetings across different languages, giving learners enough variety to build list/detail UI without needing pagination.

4.2 Storage strategy

• Data lives in a single TypeScript module (apps/api/src/data/greetings.ts) exported as an array, held in memory by the running Node process.
• Any POST/mutation made during a challenge exercise resets on server restart — this is clearly called out in the README so learners aren’t confused by “lost” data.
• No ORM, no migrations, no schema files — deliberately, to keep the backend readable in a single sitting.

4.3 Future extension path (documented, not built)

For learners who want to go further (explicitly out of the current scope, but noted as a natural “next step” so the architecture doesn’t paint them into a corner):

1. Swap the in-memory array for SQLite (via better-sqlite3) with zero infra changes — a natural first “real database” step.
2. Graduate to Postgres (e.g. Supabase or Neon free tier) with a lightweight query builder (Kysely or Drizzle) once learners are comfortable with schema/migrations concepts.
3. The Greeting TypeScript interface remains the contract boundary regardless of storage — reinforcing the idea that the API contract, not the storage engine, is what the frontend depends on.

5. API Design & Endpoints

A small, RESTful, resource-oriented API — intentionally shaped like a “real” service so the pattern transfers directly to day-job work.

Base URL (local): http://localhost:4000/api Base URL (production): configured via VITE_API_BASE_URL environment variable, consumed by the frontend at build time.

5.1 Conventions

• JSON in, JSON out, Content-Type: application/json enforced via Express middleware.
• Consistent error shape: { error: string }, so the frontend’s useGreetings hook has a single error-handling code path to teach.
• Input validation on POST kept intentionally simple (a hand-written guard function) rather than introducing a validation library like Zod — that’s flagged in the README as a “nice next step” rather than baked in, to avoid adding a concept before it’s needed.
• CORS is enabled narrowly (see §9) for the deployed frontend origin and localhost during development.

5.2 Frontend consumption pattern

A single typed hook wraps all network access, so learners see one canonical pattern rather than ad-hoc fetch calls scattered through components:

function useGreetings(): {
  data: Greeting[] | null;
  loading: boolean;
  error: string | null;
}

This hook is reused (and extended) as the basis for the “add a page that fetches something new” exercise.

6. Authentication & Authorization

Decision: out of scope by design. This was explicitly raised and descoped during discovery — introducing login flows, tokens, or protected routes would add substantial cognitive load for beginners without reinforcing the core concepts this starter is meant to teach (components, routing, styling, basic data fetching).

Implications for the architecture:

• All API endpoints are public and unauthenticated. The API is not intended to hold sensitive data — the Greeting model contains nothing user-specific or private.
• No session storage, cookies, JWTs, or identity provider integration are present anywhere in the stack.
• No route in the SPA is “protected” — all routes are publicly navigable, simplifying the router setup used for teaching.
• Rate limiting/abuse protection is intentionally minimal (see §9) since there is no account system to abuse.

Documented extension path: If a mentor later wants an “advanced” fork of this starter, a natural next challenge would be adding a mock login (e.g., a hard-coded credential check storing a flag in localStorage) to introduce the concept of protected routes without pulling in a full auth provider. This is explicitly called out as future scope, not built.

7. Infrastructure & Deployment

7.1 Repository layout

react-hello-world/
├── apps/
│   ├── web/     # Vite + React + TypeScript SPA
│   └── api/     # Express + TypeScript API
├── package.json # workspace root, "dev" script via concurrently
├── README.md    # setup instructions + challenges
└── .github/workflows/ci.yml

7.2 Local developer experience

• npm install at the repo root installs both workspaces.
• npm run dev (root) runs concurrently to start:
  • apps/web: Vite dev server on http://localhost:5173
  • apps/api: Express server (via tsx watch) on http://localhost:4000
• A .env.example file documents VITE_API_BASE_URL for the frontend and PORT for the API; learners copy it to .env as part of setup — this is intentionally the substance of the “one-command setup” challenge (get both services talking to each other locally).

7.3 CI pipeline

GitHub Actions runs on every push/PR:

1. Install dependencies (cached).
2. npm run lint (ESLint across both workspaces).
3. npm run typecheck (tsc --noEmit).
4. npm run test (Vitest, both workspaces).
5. npm run build (Vite build for web, tsc build for api).

This gives learners a realistic, fast feedback loop mirroring a real PR-gated workflow, without needing to configure anything themselves.

7.4 Deployment targets

flowchart LR
    GH[GitHub Repository] -->|push to main| CI[GitHub Actions]
    CI -->|on success| VDeploy[Vercel Build & Deploy]
    CI -->|on success| RDeploy[Render Build & Deploy]
    VDeploy --> WebProd[Static SPA - CDN]
    RDeploy --> APIProd[Express API - Node runtime]
    WebProd -->|HTTPS fetch| APIProd

• Frontend deploys as a static build to Vercel (or Netlify); every PR gets an automatic preview URL — useful if a mentor wants to share a live version for code review.
• Backend deploys to Render’s free web service tier, auto-deploying from the apps/api workspace on push to main.
• Environment variables (VITE_API_BASE_URL on the frontend host, PORT/CORS_ORIGIN on the backend host) are configured in each platform’s dashboard — never committed to the repo.
• No infrastructure-as-code tooling (Terraform, etc.) is introduced; both platforms’ dashboards are simple enough to be part of the learning experience if a mentor chooses to walk through deployment, though local-only exploration is fully sufficient for the core teaching goals.

8. Scalability Strategy

Scalability is not a primary concern for this project — it is a teaching starter, not a production system expected to handle real user load. However, the architecture avoids scalability anti-patterns so it remains a credible example of real-world structure:

• Frontend: A static SPA served via CDN (Vercel/Netlify) scales automatically to essentially unlimited concurrent learners with no additional work — there is nothing to tune.
• Backend: The Express API is stateless per-request (aside from the in-memory store), so it could be horizontally scaled trivially if the in-memory store were replaced with a shared database — a limitation explicitly documented in the README rather than hidden, so learners understand why it doesn’t scale today and what the fix would be (see §4.3).
• Data growth: The greetings dataset is intentionally small (~10 records) and not expected to grow significantly; this is a teaching fixture, not a live dataset.
• Concurrency: Multiple learners running their own local forks/clones each get an isolated process — there is no shared state between different learners’ environments, so “scale” in the traditional sense doesn’t apply to the primary use case (local exploration).
• If this starter were promoted to a real internal tool (e.g., a shared internal demo), the documented upgrade path is: swap in-memory store → SQLite/Postgres, add caching only if a specific endpoint became a bottleneck (unlikely at this scale), and move the API behind the same CDN-fronted domain as the SPA to simplify CORS.

9. Security Considerations

Even as a learning tool, the starter models sane, professional security defaults so learners absorb good habits by osmosis:

• CORS: The Express API restricts allowed origins via an environment-configured allow-list (localhost:5173 in development, the deployed frontend URL in production) rather than a wildcard *.
• Input validation: The POST /api/greetings endpoint validates required fields and rejects malformed payloads with a 400, rather than trusting client input — a small but important habit to model early.
• No secrets in the repo: .env is git-ignored; .env.example documents required variables without values. CI and hosting platforms inject real values via their own secret stores.
• Dependency hygiene: npm audit is run as part of CI (non-blocking initially, to avoid noisy failures for beginners, but visible in the CI log) so learners see dependency scanning as a normal part of the pipeline.
• XSS: React’s default JSX escaping handles output encoding; no dangerouslySetInnerHTML is used anywhere in the starter, and this constraint is called out in the README as a deliberate choice.
• Transport security: Both Vercel and Render provision HTTPS by default in production; local development over HTTP is acceptable and clearly scoped to localhost.
• No sensitive data: Because there is no authentication and no user-generated PII, the blast radius of any issue in this project is inherently low — an explicit and appropriate trade-off for a teaching tool.
• Rate limiting: Not implemented initially (unnecessary complexity for a local/teaching API), but noted as a natural “harden this for production” follow-up if the API were ever exposed more broadly.

10. Monitoring & Observability

Observability is kept intentionally lightweight, proportionate to the project’s teaching purpose, while still demonstrating the concepts learners will need at work:

• Health check endpoint (GET /api/health): used both by Render’s platform health checks and as a teaching example of how services expose liveness for orchestration.
• Structured console logging: The Express API logs method, path, and response status/time for each request via a small middleware (no external logging service required) — enough for learners to see request/response cycles while debugging locally.
• Frontend error boundary: A top-level React ErrorBoundary component catches render-time errors and displays a friendly fallback UI, rather than a blank white screen — modeling a pattern every production React app needs, and directly relevant to the “well-rounded first look” goal.
• Build-time feedback: TypeScript and ESLint errors surface immediately in the Vite dev server overlay and terminal — the fastest possible observability loop for a beginner.
• Platform-native monitoring: Both Vercel and Render provide basic request logs and deploy status out of the box; no additional tooling (Sentry, Datadog, etc.) is introduced, keeping the observability stack proportionate to the project’s scale.
• Documented (not implemented) next step: The README notes that a production version of this app would add an error-tracking service (e.g., Sentry) and structured metrics — flagged as a natural “if you outgrow this starter” upgrade rather than built in, to avoid adding accounts/config that would distract from the core learning goals.