YuvaSetu Monorepo

🏆 SIH 2025 - 1st Runner Up

This project was developed for Smart India Hackathon 2025 and secured the 1st Runner Up position.

Team Members

• Joy B (Team Leader)
• Shubham K
• Atharva C
• Nashrah A
• Anamika L
• Sharon S

---

About the Project

Central codebase for the YuvaSetu internship platform:

• Student experience – browse and apply to internships.
• Employer tools – post roles, review applicants, run AI-powered search.
• Admin controls – moderate content, manage organizations, view insights.

---

1. What lives where?

yuvasetu-monorepo/
├── backend/
│   ├── employer-admin/   FastAPI app for employer + admin portals
│   └── student/          FastAPI app for the student portal
└── frontend/
    ├── admin/            React + Vite admin UI
    ├── employer/         React + Vite employer UI
    └── student/          React + Vite student UI

---

2. What you need installed

Tool	Version	Why
Node.js	18+	All frontend apps and build tools
npm or bun	latest	Frontend package manager
Python	3.10+	FastAPI backends
pip	latest	Python deps
MongoDB	4.4+	Primary data store (local instance or remote URI)
Redis (optional)	latest	Student backend caching
Firebase project	optional	Auth for employer/admin portals

---

3. First-time setup (15–20 min)

1. Clone the repo

   git clone <repo-url>
   cd yuvasetu-monorepo

2. Install backend deps

   # Employer + admin API
   cd backend/employer-admin
   python -m venv venv && venv\Scripts\activate   # use source venv/bin/activate on macOS/Linux
   pip install -r requirements.txt
   
   # Student API
   cd ../student
   python -m venv venv && venv\Scripts\activate
   pip install -r requirements.txt

3. Install frontend deps

   cd frontend/<admin|employer|student>
   npm install   # or bun install

4. Copy env files

   cp .env.example .env

   Fill in values using the quick reference below.

5. (Only once) Build the FAISS index

   cd backend/employer-admin
   python -m app.scripts.init_faiss

---

4. How to run everything (repo root scripts)

Install deps once

cd backend/student        && pip install -r requirements.txt
cd backend/employer-admin && pip install -r requirements.txt
cd frontend/employer      && npm install
cd frontend/admin         && npm install
cd frontend/student       && npm install

Start the stack

These npm scripts wrap the correct commands and ports so you do not have to cd around. Run each one in its own terminal tab from the repo root right after MongoDB is up.

Terminal	Command	Starts	URL / Notes
1	npm run dev:be-emp	FastAPI employer/admin backend	http://127.0.0.1:8000
2	npm run dev:be-stu	FastAPI student backend	http://127.0.0.1:8001
3	npm run dev:fe-emp	Employer frontend	http://localhost:8082 (proxy /api → 8000)
4	npm run dev:fe-admin	Admin frontend	http://localhost:8081 (proxy /api → 8000)
5	npm run dev:fe-stu	Student frontend	http://localhost:8080 (API base http://127.0.0.1:8001)

• npm run dev:all only prints this order as a reminder. It does not spawn processes.
• Prefer Bun? edit the scripts or run bun run dev inside each frontend folder manually.

What was fixed / wired

• Root npm run dev:* scripts now encapsulate the uvicorn + Vite commands with the correct ports.
• Employer/admin frontends proxy /api to the employer-admin backend on 8000; the student frontend calls the student backend on 8001 via src/services/api.ts.
• npm run dev:all is intentionally a reminder so you decide how to manage processes (multiple terminals, tmux, etc.).

Health checks

curl http://127.0.0.1:8001/health   # student API
curl http://127.0.0.1:8000/health   # employer-admin API
curl http://127.0.0.1:8000/internships/health/faiss   # FAISS index

---

5. Port + URL cheat sheet

Service	Port	URL
Employer-admin backend	8000	http://127.0.0.1:8000
Student backend	8001	http://127.0.0.1:8001
Student frontend	8080	http://localhost:8080
Admin frontend	8081	http://localhost:8081
Employer frontend	8082	http://localhost:8082

All three frontends can run together. Change ports in each vite.config.ts if needed.

---

6. Environment variables (copy/paste guide)

Keep .env files out of git. Copy the matching .env.example, then edit:

App	Required keys	Notes
backend/employer-admin/.env	MONGODB_URI, MONGODB_DB, FIREBASE_SERVICE_ACCOUNT_PATH, FIREBASE_ADMIN_SERVICE_ACCOUNT_PATH	Paths can be relative or absolute. Runs on port 8000 automatically.
backend/student/.env	MONGODB_URL, DATABASE_NAME, SECRET_KEY, SMTP_*	Optional: Google OAuth (GOOGLE_*), Firebase (FIREBASE_*), REDIS_URL. Port fixed at 8001.
frontend/admin/.env	VITE_FIREBASE_*	Uses proxy to http://127.0.0.1:8000, so no API URL needed.
frontend/employer/.env	VITE_FIREBASE_*	Same proxy behaviour as admin app (→ 8000).
frontend/student/.env	VITE_API_URL=http://127.0.0.1:8001	Optional Firebase config if needed.

Tip: after editing, run npm run dev (frontends) or uvicorn ... (backends) and watch the console for missing variable errors.

---

7. Common tasks

• Run tests/builds

  # Frontend prod build
  cd frontend/<app> && npm run build
  
  # Backend prod servers
  uvicorn app.main:app --host 0.0.0.0 --port <port> --workers 4

• Deployment ideas

  • FastAPI: Gunicorn + Uvicorn workers.
  • Frontend: Deploy dist/ folder to any static host (Netlify, Vercel, S3, etc.).
  • Process managers: PM2 or systemd for multi-service setups.

---

8. Troubleshooting

Problem	Quick fix
Port in use	Stop the other process or change the port in vite.config.ts / the uvicorn command.
MongoDB errors	Ensure MongoDB is running and the URI matches your setup. Check auth requirements.
Firebase auth failing	Verify service account JSON paths and frontend VITE_FIREBASE_* values.
FAISS index missing	Run python -m app.scripts.init_faiss inside backend/employer-admin.
Import/path issues	Confirm path aliases in tsconfig.json + vite.config.ts, and BASE_DIR settings in the backends.

---

9. Extra docs

• backend/employer-admin/QUICKSTART.md
• backend/employer-admin/README_SEMANTIC_SEARCH.md
• backend/student/README.md (if present)
• Frontend-specific READMEs inside each app folder

---

10. License & contributors

Fill in the sections below once you choose a license and list maintainers:

• LICENSE
• README.md → add your contributor list when ready.