Jackalope-Dev · moxie-docs · Jun 26, 2026
diff --git a/moxie-docs/backend/backend-server.md b/moxie-docs/backend/backend-server.md
@@ -0,0 +1,87 @@
+# Backend server.js — Express API and health endpoint
+
+This area contains a minimal Express-based HTTP server that provides a simple JSON API consumed by the frontend and a health probe endpoint. It centralizes CORS configuration, JSON body parsing, and port selection via the `PORT` environment variable.
+
+## Architecture
+
+- Entry point: `backend/server.js` instantiates an Express app and starts listening.
+- Dependencies: `express` for routing/middleware, `cors` for cross-origin requests; declared in `backend/package.json`.
+- Middleware stack (in order):
+  - `cors()` (allows all origins by default)
+  - `express.json()` (parses JSON request bodies)
+- Routes:
+  - `GET /api/project` returns static project metadata as JSON
+  - `GET /healthz` returns plain text OK for health checks
+- Process config: `PORT` env var, default `5000`.
+
+## backend/server.js
+
+Responsibility
+- Bootstraps an Express server, configures CORS and JSON parsing, defines two routes, and starts listening on the configured port.
+
+Control and data flow
+- Process starts: `const app = express();` and selects `PORT = process.env.PORT || 5000`.
+- Middleware:
+  - `app.use(cors());` allows cross-origin requests from any origin. A commented block illustrates how to restrict origin/methods if needed.
+  - `app.use(express.json());` attaches JSON body parsing for downstream routes (current routes are GET-only and do not consume bodies, but this enables future POST/PUT routes to read `req.body`).
+- Routes:
+  - `GET /api/project`
+    - Path: `/api/project`
+    - Methods: GET
+    - Auth: None; no authentication or authorization is implemented.
+    - Inputs: No path params, query params, or request body are read.
+    - Response: `200 OK` with JSON payload:
+      {
+        studentName: "Smith, John",
+        projectName: "Weather App",
+        projectUrl: "http://10.0.0.1:3000/",
+        projectDescription: "This application provides real-time weather updates for any location worldwide."
+      }
+    - Errors: None explicitly handled; default Express error handling would apply if an unexpected exception occurs (not expected in current static response).
+    - Side effects: None.
+  - `GET /healthz`
+    - Path: `/healthz`
+    - Methods: GET
+    - Auth: None.
+    - Inputs: None.
+    - Response: `200 OK` with plain text body `OK` (via `res.send('OK')`). Content-Type will be `text/html; charset=utf-8` by Express default for string sends, which is acceptable for health checks.
+    - Errors: None explicitly handled.
+- Server start: `app.listen(PORT, () => { console.log(
+    \`Server running on port ${PORT}\`
+  ); });`
+
+Client interactions
+- Frontend or external clients can call `GET {server-origin}/api/project` to retrieve project metadata for display.
+- Liveness probes or monitoring can call `GET {server-origin}/healthz` to confirm process responsiveness.
+
+## backend/package.json
+
+- Declares runtime dependencies used by `server.js`:
+  - `express@^4.21.1`
+  - `cors@^2.8.5`
+- Scripts: Only a placeholder `test` script is defined; there is no start script here. Consumers should run the server with a Node command, e.g., `node backend/server.js`, or define an appropriate `start` script.
+- Main is `index.js`, but this is unused by the current setup; `server.js` is the actual entrypoint.
+
+## API details
+
+- Base URL: This server binds to `http://0.0.0.0:{PORT}` as determined by Node/Express default; external reachability depends on deployment. Default port is `5000` unless `PORT` is set.
+
+- Endpoint: GET /api/project
+  - Request: No auth or parameters.
+  - Response: 200 with JSON body shown above.
+
+- Endpoint: GET /healthz
+  - Request: No auth or parameters.
+  - Response: 200 with body `OK`.
+
+## Gotchas
+
+- CORS configuration: `app.use(cors())` allows all origins and methods by default. If the frontend must be restricted (e.g., to `http://localhost:3000`) or methods limited, replace with the commented configuration block in `server.js`. Be careful to include all methods your frontend uses (e.g., `OPTIONS` for preflight, `GET`, `POST`). Overly restrictive settings can break browsers with CORS errors.
+
+- Port selection: The server depends on `process.env.PORT` when present; ensure your deployment sets it, or expect port `5000`. Port conflicts will prevent startup.
+
+- Content types: `/api/project` uses `res.json(...)` which sets `application/json`. `/healthz` uses `res.send('OK')`, resulting in a text response. If your health checker expects JSON, adjust accordingly.
+
+- Lack of auth and validation: All routes are public and accept cross-origin access. Do not add sensitive data without implementing authentication/authorization and tightening CORS.
+
+- Missing start script: Since `package.json` lacks a `start` script, some tooling may not auto-run the server. Use `node backend/server.js` or add a script before relying on package scripts.
diff --git a/moxie-docs/reference/package.md b/moxie-docs/reference/package.md
@@ -0,0 +1,93 @@
+# Run and develop: combined workflow for fullstack (root + backend + frontend)
+
+This area defines how to install, start, and develop the React frontend and Node.js/Express backend together from the repository root. It exists to provide a single entry point for running both apps concurrently, while allowing each app to be developed independently when needed.
+
+## Architecture
+
+- Root orchestrator: `package.json` at repo root wires concurrent dev workflow and delegates to backend and frontend.
+- Backend app: `backend/` (Express + CORS). Started via nodemon from the root orchestrator.
+- Frontend app: `frontend/` (Create React App). Started via `react-scripts` from the root orchestrator using `--prefix`.
+- Control flow for `npm start` at root:
+  - Spawns two processes in parallel: `npm run server` (backend) and `npm run client` (frontend).
+  - Backend entry (nodemon) watches `backend/server.js` (by convention) and restarts on file changes.
+  - Frontend entry (CRA) starts the dev server with hot reload.
+
+## Root package.json (./package.json)
+
+Responsibility: Single-command developer workflow and shared dev dependencies for running both servers concurrently.
+
+Key scripts and behavior:
+- "start": `concurrently "npm run server" "npm run client"`
+  - Entry point for fullstack development. Spawns both backend and frontend. Output is interleaved by concurrently.
+- "server": `nodemon backend/server.js`
+  - Starts the backend using nodemon. Expects `backend/server.js` to exist and export/start an Express app.
+- "client": `npm start --prefix frontend`
+  - Starts the frontend by running the `start` script from `frontend/package.json`.
+
+Dependencies used by the workflow:
+- `concurrently`: Runs multiple scripts in parallel from a single command.
+- `nodemon`: Restarts the backend process on file changes.
+
+Ports and interaction:
+- The README documents the expected ports during development:
+  - Frontend (CRA): http://localhost:3000
+  - Backend (Express): http://localhost:5000
+- Cross-origin development is expected; the backend should enable CORS to accept requests from the frontend’s origin.
+
+What happens on change:
+- Editing backend files (e.g., `backend/server.js`) triggers nodemon to restart the server process.
+- Editing frontend files triggers CRA’s hot reload.
+
+## Backend package.json (./backend/package.json)
+
+Responsibility: Backend app dependencies and local scripts (none defined for starting; start is driven from root).
+
+Important contents:
+- Dependencies: `express`, `cors`
+  - Backend is an Express server with CORS enabled to support cross-origin requests from the CRA dev server.
+- No `start` script is defined here; the backend is started from root via `nodemon backend/server.js`.
+
+Implications:
+- The backend entry file is assumed by the root script to be `backend/server.js`.
+- If you rename or relocate the backend entry, you must update the root `server` script accordingly.
+
+## Frontend package.json (./frontend/package.json)
+
+Responsibility: Frontend (Create React App) dependencies and scripts.
+
+Key scripts:
+- "start": `react-scripts start`
+  - Starts the CRA dev server (default on port 3000). Consumed by root via `npm start --prefix frontend`.
+- "build": `react-scripts build`
+- "test": `react-scripts test`
+- "eject": `react-scripts eject`
+
+Runtime behavior:
+- CRA serves the React app, provides hot reload, and proxies are not configured here. Calls to the backend should use the full backend URL (e.g., `http://localhost:5000/...`) unless you add a CRA proxy configuration.
+
+## README.md (./README.md)
+
+Responsibility: User-facing guide for setup and run instructions, ports, and how the two apps interact.
+
+Highlights grounded in source:
+- Install: `npm install` at root. If needed, install separately in `frontend` and `backend`.
+- Start both: `npm start` (runs the root script via `concurrently`).
+  - Frontend: `http://localhost:3000`
+  - Backend: `http://localhost:5000`
+- Start only backend: `npm run server`
+- Start only frontend: `npm run client`
+- CORS must be enabled in the backend to allow the frontend to call it across ports (backend `cors` dependency confirms intent).
+- Example API route shown in the README references `backend/server.js` and uses `app.get('/api/project', ...)` returning JSON, and frontend fetch example uses `http://localhost:5000/api/project`.
+
+Contracts and data flow:
+- Frontend calls backend over HTTP using absolute URLs (no CRA proxy configured here).
+- Backend responds with JSON; the README’s example returns fields like `studentName`, `projectName`, `projectUrl`, `projectDescription`.
+
+## Gotchas
+
+- Backend entry path is hardcoded in root script: The root `server` script runs `nodemon backend/server.js`. If your backend entry file isn’t `backend/server.js`, update the root script accordingly or your start will fail.
+- Ports are implied, not enforced in scripts: The README states 3000 (frontend) and 5000 (backend). Ensure your backend actually listens on 5000 or update documentation and frontend calls to match. CRA will prompt to use a different port if 3000 is busy; that will break hardcoded frontend fetch URLs unless you adjust them.
+- CORS must be enabled in the backend: The cross-origin dev flow requires `cors` middleware in your Express app. If omitted or misconfigured, the frontend will see CORS errors even if the backend endpoint works.
+- No CRA proxy configured: Since there is no `proxy` field in `frontend/package.json`, the frontend must call fully-qualified backend URLs. If you add a proxy later, remove hardcoded host/port in frontend code or you’ll get mixed-origin behavior depending on environment.
+- Independent node_modules: The root has devDependencies (`concurrently`, `nodemon`) while backend/frontend have their own dependencies. Running `npm install` at root installs only root deps. Install app-specific deps in their respective directories when adding packages.
+- Start order and readiness: `concurrently` starts both servers in parallel; the frontend may attempt requests before the backend is ready. Handle retries or conditional rendering in the frontend.