scalesApp/.claude/plans/change-dev-ports-backend-8002-frontend-5172.md

Plan: Move local dev ports (backend 8000 → 8002, frontend 3000 → 5172)

User Request

ok, so, server is set to run on 8000, but I want it to be on 8002, also the frontend - what port is it? I want it to be on 5172 (for the local npm rundev)

Plan

Context

The local development ports collide with other things running on this machine. The user wants the Django backend on 8002 instead of 8000, and the React frontend on 5172 instead of 3000.

Two findings shaped this plan:

1. The frontend is Create React App (react-scripts 5.0.1), not Vite. There is no dev script and no vite.config. The user asked for "npm run dev" on 5172 — a Vite-shaped request. Rather than migrate the build tool (out of scope), we set CRA's PORT env var to 5172 and add a dev script alias so npm run dev works as expected.
2. Changing the ports is not just two edits. Three other places hardcode the old ports and would silently break: the frontend's API base URL, CRA's dev proxy, and the backend's CORS allow-list (which would reject the frontend's new origin).

Scope is local dev only. Docker (backend/Dockerfile, docker-compose.yml) keeps port 8000 — it is container-internal there and the host mapping 8101:8000 is what you actually connect to. Docs (README/SETUP/CLAUDE.md) are left as-is per the user's choice.

Changes

1. Backend port → 8002

run_server.bat:4 — the only place the local server port is set:

uvicorn scalesapp.asgi:application --host 127.0.0.1 --port 8002 --reload

2. Frontend port → 5172 and API URL → 8002

frontend/.env (currently one line, REACT_APP_API_URL=http://localhost:8000):

PORT=5172
REACT_APP_API_URL=http://localhost:8002

PORT is the standard CRA dev-server port variable — no config file needed. Note CRA only reads .env at dev-server start, so the server must be restarted, not just reloaded.

frontend/.env.example:1 — mirror the same two lines so the template stays accurate.

3. npm run dev alias

frontend/package.json:13-18 — add a dev script next to the existing start:

"start": "react-scripts start",
"dev": "react-scripts start",

4. CRA dev proxy → 8002

frontend/package.json:36:

"proxy": "http://localhost:8002"

5. CORS allow-list → add 5172

backend/scalesapp/settings.py:108 — without this the browser blocks every API call from the new origin:

_cors_default = 'http://localhost:5172,http://127.0.0.1:5172,http://localhost:3000,http://127.0.0.1:3000,http://localhost:5174,http://127.0.0.1:5174'

Existing 3000/5174 entries are kept — they cost nothing and avoid breaking any other local setup. This is only the default; an explicit CORS_ALLOWED_ORIGINS in backend/.env would override it, and there is currently none, so the default applies.

Not changed (deliberately)

• backend/Dockerfile, docker-compose.yml — container-internal 8000, host port 8101.
• frontend/src/services/api.js:3, contexts/NomenclatureContext.jsx:3 — their http://localhost:8000 is a fallback only, superseded by REACT_APP_API_URL.
• serial_bridge/ — runs on 5000, talks to Django only via BACKEND_URL; unaffected unless the bridge needs to reach the backend (it currently pushes nothing on startup).
• README.md, SETUP.md, CLAUDE.md port references.

Verification

1. run_server.bat → console shows Uvicorn running on http://127.0.0.1:8002. Confirm http://127.0.0.1:8002/api/ responds (401/403 is fine — it proves it's up).
2. cd frontend && npm run dev → console shows On Your Network: http://localhost:5172 and the browser opens there.
3. Log in through the UI. This is the real end-to-end check: it exercises POST /api/token/ cross-origin from localhost:5172 to localhost:8002, so it validates the API URL and the CORS entry together.
4. Open DevTools → Network: no CORS errors, and the /sse-connect/ EventSource shows status 200 and stays open (SSE is authenticated via query-param token and is the most likely thing to break silently if a port was missed).
5. Confirm nothing still calls 8000: with the app running, check the Network tab for any request to localhost:8000.