Sarthi - IIITG Community Hub

Sarthi is a comprehensive microservices-based web application designed for the IIIT Guwahati community. It bridges the gap between students, faculty, and staff by providing essential campus utilities like peer-to-peer carpooling and a dedicated marketplace.

1. Requirement Analysis

The application was built to address specific needs within the campus ecosystem, focusing on trust and role-based access.

📄 Detailed Requirements:

Core Modules

Authentication & Roles: Secure Google OAuth sign-in with distinct roles:
- Students: Authenticated via domain-specific email (@iiitg.ac.in student domain).
- Faculty: Authenticated via domain-specific email (@iiitg.ac.in faculty domain).
- Staff: No domain-specific verification required.
Ride Sharing (Carpooling):
- Post ride requests or offer rides.
- Real-time status updates (Pending, Accepted, Rejected).
- Integrated Chat for coordination between rider and driver.
Campus Marketplace:
- Buy and sell items within the trusted campus network.
- Upload product images and details.
User Profiles: Manage personal details, view outgoing/incoming requests, and history.

2. Design (Microservices Architecture)

The system follows a Microservices Architecture, separating concerns into distinct, independently deployable services.

📐 Architecture Diagrams:

Service Breakdown

Auth Service (/Back-end/auth-service):
- Handles Google OAuth via Passport.js strategies.
- Manages user creation, role assignment, and JWT token issuance.
- Connects to MongoDB users collection.
Ride Service (/Back-end/ride-service):
- Manages ride listings, ride requests, and status updates.
- Socket.IO Server: Handles real-time chat and live notifications for ride updates.
Marketplace Service (/Back-end/marketplace-service):
- Handles product listings (CRUD operations).
- Manages interactions between buyers and sellers.
Frontend (/Front-end):
- Single Page Application (SPA) built with React & Vite.
- Communicates with all three backend services via REST APIs.

3. Development (MERN Stack)

The application is built using the MERN stack, optimized for performance and scalability.

Tech Stack

MongoDB (Atlas): Cloud-native NoSQL database for storing users, rides, chats, and market listings.
Express.js: Lightweight backend framework used in all three microservices.
React.js (Vite): Fast, modern frontend library for the user interface.
Node.js: Runtime environment for all backend services.

Key Libraries

Frontend: axios (API requests), socket.io-client (Real-time), react-router-dom (Navigation), framer-motion (Animations).
Backend: mongoose (ODM), passport-google-oauth20 (Auth), socket.io (WebSockets), cors (Cross-origin security).

4. Integration

Integration is handled through RESTful APIs and WebSockets, ensuring seamless communication between independent services.

API Gateway Pattern: The Frontend acts as the consumer, routing requests to the appropriate microservice based on the URL path:
- /api/auth → Auth Service (Port 5001)
- /api/rides → Ride Service (Port 5003)
- /api/listings → Marketplace Service (Port 5000)
Real-Time Communication:
- The Ride Service hosts a Socket.io server.
- The Frontend connects to this socket to push chat messages and receive instant alerts when a ride request is accepted.
Environment Configuration: Centralized configuration (config.js) dynamically switches between localhost for development and Render URLs for production.

5. Testing

We employ a robust testing strategy covering both API logic and End-to-End (E2E) user flows.

Test Cases

Our testing strategy covers both System-level user flows (via Cypress) and API Contract logic (via Postman). Below are the specific test cases automated in this repository.

Postman (API Testing)

Collection: Sarthi API.postman_collection.json
Tests cover:
- User authentication flows.
- CRUD operations for Rides and Marketplace listings.
- Socket connection validation.

A. Integration Testing (API)

Automated using Postman Collection Sarthi API.postman_test_run.json

ID	Service	Endpoint	Test Description	Assertions
API-01	Auth	`POST /auth/google`	Validate Google Login logic	Status 200; Token exists in response
API-02	Auth	`GET /user/me`	Fetch User Profile	Status 200; Email field matches token
API-03	Auth	`PUT /user/me`	Update User Details	Status 200; `fullName` updates correctly
API-04	Ride	`POST /rides`	Create a Ride	Status 201; Response contains Ride ID
API-05	Ride	`GET /rides`	Fetch All Rides	Status 200; Response is an Array
API-06	Market	`POST /listings`	Create Listing	Status 201; Response contains Listing Title
API-07	Market	`GET /listings`	Fetch All Listings	Status 200; Response is an Array

Cypress (E2E Testing)

Located in cypress/e2e, our suites simulate real user behavior:

01-authentication.cy.js: Verifies Google Login and Role selection.
02-create-ride.cy.js: Tests the flow of creating and publishing a ride.
03-marketplace.cy.js: Validates adding items to the marketplace.
04-user-profile.cy.js: Ensures profile updates persist correctly.
05-error-handling.cy.js: Checks system resilience against network failures or invalid inputs.

B. System Testing (End-to-End)

Automated using Cypress in cypress/e2e

ID	Module	Test Scenario	Expected Outcome	Source File
TC-01	Auth	User logs in as Student	Redirects to Home; "Welcome" message visible	`01-authentication.cy.js`
TC-02	Ride	Navigate to "Offer a Ride"	URL changes to `/create-ride`; Form loads	`02-create-ride.cy.js`
TC-03	Ride	Submit Ride Form	API returns 201; Redirects to Home; Success alert	`02-create-ride.cy.js`
TC-04	Ride	Submit Empty Form	HTML5 validation prevents submission	`02-create-ride.cy.js`
TC-05	Market	View Marketplace	Page loads; Listings are visible	`03-marketplace.cy.js`
TC-06	Market	Open "Sell Item" Form	Clicking "+ Sell Item" reveals input fields	`03-marketplace.cy.js`
TC-07	Market	Create New Listing	Form fills correctly; "Publish" triggers 201 POST	`03-marketplace.cy.js`
TC-08	Profile	View Profile Data	User details (Name, Dept) populate input fields	`04-user-profile.cy.js`
TC-09	Profile	Update Profile	Changing name and clicking "Save" updates UI	`04-user-profile.cy.js`
TC-10	Error	Backend Failure (500)	UI displays "Internal Server Error" message gracefully	`05-error-handling.cy.js`
TC-11	Error	Network Disconnect	Marketplace shows "Network Error" state	`05-error-handling.cy.js`
TC-12	Error	Unauthorized Access (401)	Profile page shows "Authentication Failed"	`05-error-handling.cy.js`

To run tests: In root directory

npx cypress open

6. Production (Docker & Render)

The application is containerized and deployed to the cloud for accessibility.

Docker

Each service includes its own Dockerfile, and the entire stack can be orchestrated locally using docker-compose.yml.

Run locally with Docker:

docker-compose up --build

Deployment (Render)

The application is live on Render, split into four separate services:

Auth Web Service: Node.js runtime.
Ride Web Service: Node.js runtime.
Marketplace Web Service: Node.js runtime.
Frontend Static Site: React/Vite build.

Environment Variables (Production)

MONGO_URI: MongoDB Atlas Connection String.
JWT_SECRET: Secure token signature.
GOOGLE_CLIENT_ID: OAuth credential.
VITE_AUTH_URL, VITE_RIDE_URL, VITE_MARKETPLACE_URL: Service inter-links.

Getting Started

Prerequisites

Node.js (v16 or higher)
MongoDB Atlas account or local MongoDB instance
Google OAuth credentials
Docker (optional, for containerized deployment)

Installation

Clone the repository

git clone https://github.com/ringerH/IIITG_Sarthi.git
cd sarthi

Install dependencies for each service

# Auth Service
cd Back-end/auth-service
npm install

# Ride Service
cd ../ride-service
npm install

# Marketplace Service
cd ../marketplace-service
npm install

# Frontend
cd ../../Front-end
npm install

Configure environment variables

Create .env files in each service directory with the required variables (see Environment Variables section).

Start the services

# Start each service in separate terminals
cd Back-end/auth-service && npm start
cd Back-end/ride-service && npm start
cd Back-end/marketplace-service && npm start
cd Front-end && npm run dev

Screenshots

Home Page

Ride Sharing Interface

Marketplace

User Profile

Real-time Chat

Documentation

For detailed documentation on specific topics, please refer to the /docs directory:

API Documentation - Complete API reference for all services

Contributing

We welcome contributions to Sarthi! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact & Support

For questions or support, please open an issue on GitHub or contact the development team at [your-email@iiitg.ac.in].

Built with ❤️ for the IIIT Guwahati Community

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
Back-end		Back-end
Front-end		Front-end
cypress		cypress
docs		docs
.DS_Store		.DS_Store
.dockerignore		.dockerignore
.gitignore		.gitignore
README.md		README.md
Sarthi API.postman_test_run.json		Sarthi API.postman_test_run.json
cypress.config.js		cypress.config.js
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
postman-tests.json		postman-tests.json

ringerH/IIITG_Sarthi

Folders and files

Latest commit

History

Repository files navigation