Career equity desk for first--gen students — onboarding, profile, résumé draft, professor matching, and a side chat. Built for hackathons; FastAPI + Next.js 14.

• Base44: https://pretty-scholaris-career-desk.base44.app
• Vercel: https://scholarisapp.vercel.app

From the repository root (Los-Altos-Hacks/).

1. Install Python deps (once):

   cd backend
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   cd ..

2. Install Node deps (once):

   npm install --prefix frontend
   npm install

3. Start everything:

   npm run dev

This runs FastAPI on http://127.0.0.1:8000 and Next.js on http://localhost:3000. Open the app at http://localhost:3000 (the UI proxies /api/* to the API).

WATCHPACK_POLLING=true is set automatically for the web process on macOS-style watcher limits.

If you prefer separate shells:

API

cd backend
.venv/bin/uvicorn main:app --reload --host 127.0.0.1 --port 8000

Web

cd frontend
npm install
WATCHPACK_POLLING=true npm run dev

Profile data is stored in backend/data/profile.json when MongoDB is not configured (see .env.example).

The frontend folder sits next to backend, not inside it. From backend/ use cd ../frontend, or open a new shell at the repo root and cd frontend.

1. Landing (/) — hero and entry points.
2. Login (/login) — demo login (name + email; password ignored).
3. Survey (/survey) — step-by-step profile; saves to the API and marks onboarding complete in the browser.
4. Desk (/dashboard, /resume, /research/professors) — main app shell + chat. Sign out clears session and sends you home.

Session flags live in localStorage (scholaris_auth, scholaris_onboarding_v1; older launchpad_* keys are migrated automatically). See frontend/lib/session.ts.

School snippet: the dashboard calls GET /api/university/summary?school=…, which fetches a short Wikipedia extract when an article title matches the school name you entered (best-effort; try the official full name if nothing shows up).

In development, the browser calls same-origin paths like /api/profile. app/api/[[...path]]/route.ts proxies those requests to FastAPI (default http://127.0.0.1:8000), which avoids Safari and other “Load failed” issues when talking straight to 127.0.0.1:8000 from the page.

• For local dev, you usually do not need NEXT_PUBLIC_API_URL in frontend/.env.local.
• If FastAPI is not on port 8000, set INTERNAL_API_URL when starting Next (see .env.example).
• After changing env files, restart npm run dev.

For production with a different API host than the default Render URL, set INTERNAL_API_URL (see .env.example).

Yes — you have to deploy the app somewhere that runs Next.js first. Changing only this repo does not change what your domain shows: scholarisapp.tech is wired for GitHub Pages (this repo has a root CNAME file with that hostname). GitHub Pages never runs next build or a Node server; it only serves static files from the branch. With no real site build there, you often just see the README (or a blank page).

1. Create a deployment
   Sign in at vercel.com → Add New… → Project → import this GitHub repo.
   Important: under Settings → General → Root Directory, set frontend (recommended). That makes Vercel use frontend/package.json, where next is declared, and avoids monorepo path bugs.
   If you leave Root Directory empty instead, the repo root package.json also lists next and postinstall installs frontend/ deps before npm run build runs.

2. Point Vercel at your live FastAPI
   The repo’s render.yaml uses the web service name scholaris-api, so the Next /api proxy defaults to https://scholaris-api.onrender.com on Vercel/Netlify when you have not set any API env vars. If your Render URL is different, set INTERNAL_API_URL in Vercel → Settings → Environment Variables (no trailing slash, no /api suffix) — it overrides the default. Redeploy after changing env.

   Optional: NEXT_PUBLIC_API_URL same as INTERNAL_API_URL only if you want the browser to call the API host directly (otherwise same-origin /api is enough).

3. Confirm the preview URL
   Open the *.vercel.app URL Vercel gives you and make sure the Scholaris UI loads. Open /api/health on the same deployment (e.g. https://yoursite.vercel.app/api/health) — you should see JSON from FastAPI (often {"status":"ok",...}), not a 503.

4. Attach your domain in Vercel
   Project → Settings → Domains → add scholarisapp.tech (and www if you want). Vercel will show the exact DNS records (usually A records for the apex, or a CNAME for www).

5. Move DNS at your registrar (where you bought .tech)
   Remove records that point the apex or www at GitHub (185.199.108.x style IPs or username.github.io). Add only what Vercel shows. DNS can take a few minutes to 48 hours.

6. Turn off GitHub Pages for this domain (avoids conflicts)
   GitHub repo → Settings → Pages → clear Custom domain / set source to None, save.
   You can delete the repo-root CNAME file after that if you are fully on Vercel (it only exists for Pages).

Set INTERNAL_API_URL on the host if your API is not the default https://scholaris-api.onrender.com. Deploy the backend separately — see backend/DEPLOY_API.md (Render walkthrough; render.yaml at repo root).

Copy .env.example and follow the comments:

• frontend/.env.local — optional frontend overrides.
• backend/.env — GOOGLE_GEMINI_API_KEY for real LLM replies (otherwise the app uses rule-based fallbacks).

Full product vision, stack targets, and stretch modules are in SCHOLARIS.md. Optional services (MongoDB Atlas, OAuth) are outlined there and in .env.example.