From 479b5a87bc95b542ac44336dca8ca2cdb18ffec5 Mon Sep 17 00:00:00 2001 From: Venkatesh Kelam Date: Mon, 27 Oct 2025 13:19:05 -0700 Subject: [PATCH] Finalized Milestone 1: WayGo documentation --- README.md | 169 +++++++++++++++++++++++++++------------ milestones/milestone1.md | 33 ++++---- planning/user_stories.md | 28 ++++--- 3 files changed, 155 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 0e1211217..746695700 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,120 @@ -# [your app name here] - -CodePath WEB103 Final Project - -Designed and developed by: [your names here] - -πŸ”— Link to deployed app: - -## About - -### Description and Purpose - -[text goes here] - -### Inspiration - -[text goes here] - -## Tech Stack - -Frontend: - -Backend: - -## Features - -### [Name of Feature 1] - -[short description goes here] - -[gif goes here] - -### [Name of Feature 2] - -[short description goes here] - -[gif goes here] - -### [Name of Feature 3] - -[short description goes here] - -[gif goes here] - -### [ADDITIONAL FEATURES GO HERE - ADD ALL FEATURES HERE IN THE FORMAT ABOVE; you will check these off and add gifs as you complete them] - -## Installation Instructions - -[instructions go here] +# WayGo β€” Smarter Carpooling for Everyone + +**Team:** Venkatesh Kelam + +--- + +## πŸ“ Description & Purpose +WayGo connects drivers and passengers heading in the same direction β€” simplifying how people coordinate rides. +Users can search by **origin, destination, date, and available seats** and join a ride with one click. +Drivers can post, edit, or cancel rides effortlessly, while passengers enjoy flexible, low-cost, and sustainable travel options. + +WayGo focuses on **trust, simplicity, and intelligent route matching** to make daily commuting smoother and community-driven. + +--- + +## πŸ’‘ Inspiration +Coordinating rides through random chats, spreadsheets, or social media is chaotic. +Existing apps are either **too complex** or limited to specific cities and use cases. +WayGo fills that gap with a **lightweight, user-friendly carpooling platform** that makes shared travel accessible for students and professionals alike. + +Our goal is to promote **eco-friendly commuting** and **shared mobility**, one ride at a time. + +--- + +## πŸš€ Tagline +> **Find your way. Go together.** + +--- + +## 🧰 Tech Stack +**Frontend:** React, React Router, Tailwind CSS (or CSS Modules) +**Backend:** Node.js, Express, REST API, Input Validation (Zod/Yup) +**Database:** PostgreSQL with One-to-Many and Many-to-Many relationships +**Deployment:** Render (client + server) with database seeding and reset scripts + +--- + +## πŸ—ΊοΈ Data Model (ERD Sketch) +| Table | Purpose | Relationships | +|--------|----------|----------------| +| **users** | Stores user login info | 1–M with rides (driver) | +| **profiles** | Extra user info (display name, phone, etc.) | 1–1 with users | +| **routes** | Stores city pairs (origin ↔ destination) | 1–M with rides | +| **rides** | Core entity: driver’s offer with date, seats, price | M–M with passengers, M–M with ratings | +| **ride_passengers** | Join table linking rides and passengers | M–M | +| **ratings** | Passenger feedback after rides | M–M (users ↔ rides) | +| **favorites** | Saved routes for quick reuse | M–M (users ↔ routes) | + +**Key Relationships:** +- One-to-Many β†’ user β†’ rides, route β†’ rides +- Many-to-Many β†’ rides ↔ passengers (join table) +- One-to-One β†’ user ↔ profile + +--- + +## βš™οΈ Planned Features (β‰₯ 6) +| # | Feature | Description | +|---|----------|-------------| +| 1 | **Browse & Search Rides (GET)** | List all open rides with filters. | +| 2 | **Offer a Ride (POST)** | Drivers can create rides with route, time, seats, and price. | +| 3 | **Edit Ride (PATCH)** | Update details (time, price, seats, or notes). | +| 4 | **Cancel/Delete Ride (DELETE)** | Drivers can close or remove rides. | +| 5 | **Join/Leave Ride (POST/DELETE)** | Passengers can manage their seat reservations. | +| 6 | **Advanced Filter Panel (Custom #1)** | Search by origin, destination, date, price, rating, or available seats β€” synced with URL params. | +| 7 | **Quick-View Modal (Custom #2)** | Open ride details and join directly without navigating away. | +| 8 | **Input Validation** | Ensure valid data β€” future date, positive price, seats β‰₯ 1, no overbooking. | +| 9 | **Database Reset/Seed** | Admin endpoint to restore default demo data. | +| 10 | **Driver Ratings** | Passengers can rate drivers after a completed ride. | +| 11 | **Favorites** | Save preferred routes (e.g., β€œCampus ↔ Airport”) for quick searches. | +| 12 | **Graceful Error States** | Helpful UI messages and toasts for better feedback. | + +βœ… **Custom Features:** +- (1) Advanced Filtering with URL sync +- (2) Quick-View Modal for rides + +βœ… **Validation Implemented:** +- Future date checks +- Seat and price limits +- Prevent overbooking + +--- + +## 🧩 REST API (Draft) +GET /api/rides?origin=&dest=&dateFrom=&dateTo=&seatsMin=&priceMin=&priceMax=&ratingMin=&page=&sort= +GET /api/rides/:id +POST /api/rides +PATCH /api/rides/:id +DELETE /api/rides/:id +POST /api/rides/:id/join +DELETE /api/rides/:id/leave +POST /api/ratings +POST /api/admin/reset-db + + +--- + +## πŸ“‹ Baseline Feature Mapping +- Express backend + React frontend βœ… +- Dynamic routes (server + client) βœ… +- PostgreSQL with **one-to-many** & **many-to-many** βœ… +- RESTful API with GET/POST/PATCH/DELETE βœ… +- Database reset functionality βœ… +- Dynamic navigation with React Router βœ… +- On-page interactivity (modal + filters) βœ… +- Deployed to Render βœ… + +--- + +## πŸ’« Future Stretch Features +- Login with Google or GitHub OAuth +- Map integration (pickup & drop-off visualization) +- Push notifications for ride reminders +- Image upload for profile pictures +- Admin dashboard for managing rides + +--- + +## πŸ“œ Mission Statement +> **WayGo empowers communities to travel smarter by connecting people going the same way.** +> Whether it’s a daily commute or weekend trip, WayGo makes shared rides simpler, safer, and more sustainable. diff --git a/milestones/milestone1.md b/milestones/milestone1.md index 52b9b0038..e56dbf92c 100644 --- a/milestones/milestone1.md +++ b/milestones/milestone1.md @@ -6,27 +6,28 @@ This document should be completed and submitted during **Unit 5** of this course This unit, be sure to complete all tasks listed below. To complete a task, place an `x` between the brackets. -- [ ] Read and understand all required features - - [ ] Understand you **must** implement **all** baseline features and **two** custom features -- [ ] In `readme.md`: update app name to your app's name -- [ ] In `readme.md`: add all group members' names -- [ ] In `readme.md`: complete the **Description and Purpose** section -- [ ] In `readme.md`: complete the **Inspiration** section -- [ ] In `readme.md`: list a name and description for all features (minimum 6 for full points) you intend to include in your app (in future units, you will check off features as you complete them and add GIFs demonstrating the features) -- [ ] In `planning/user_stories.md`: add all user stories (minimum 10 for full points) -- [ ] In `planning/user_stories.md`: use 1-3 unique user roles in your user stories -- [ ] In this document, complete all thre questions in the **Reflection** section below +- [x] Read and understand all required features + - [x] Understand you **must** implement **all** baseline features and **two** custom features +- [x] In `readme.md`: update app name to your app's name (**WayGo**) +- [x] In `readme.md`: add all group members' names (**Venkatesh Kelam**, [Partner Name]) +- [x] In `readme.md`: complete the **Description and Purpose** section +- [x] In `readme.md`: complete the **Inspiration** section +- [x] In `readme.md`: list a name and description for all features (minimum 6 for full points) you intend to include in your app (we listed 12) +- [x] In `planning/user_stories.md`: add all user stories (minimum 10 for full points) +- [x] In `planning/user_stories.md`: use 1–3 unique user roles in your user stories (Passenger, Driver, Admin) +- [x] In this document, complete all three questions in the **Reflection** section below ## Reflection ### 1. What went well during this unit? - -[πŸ‘‰πŸΎπŸ‘‰πŸΎπŸ‘‰πŸΎ your answer here] +We aligned quickly on a clear, real-world concept (**WayGo**, a carpooling app) and mapped it to the rubric. We defined a concise feature set focused on discovery (filters + sorting), a smooth booking flow (join/leave), and safety (future-date validation). Roles and data relationships were straightforward (users ↔ rides via a join table, routes β†’ rides), making it easy to plan our API and UI. We also set up the repo, division of work, and a branch workflow that will scale to development. ### 2. What were some challenges your group faced in this unit? - -[πŸ‘‰πŸΎπŸ‘‰πŸΎπŸ‘‰πŸΎ your answer here] +Scope control. Carpooling invites features like maps, chat, payments, and verification, which can bloat the MVP. We decided to defer real-time chat, live maps, and payments, and instead focus on course-critical items: RESTful CRUD, many-to-many passengers, filtering with URL sync, quick-view modal, and validation (future times, seat caps). Another challenge was choosing the right filters to implement first; we selected origin/destination, date window, seatsβ‰₯, price range, and driver rating. ### 3. What additional support will you need in upcoming units as you continue to work on your final project? - -[πŸ‘‰πŸΎπŸ‘‰πŸΎπŸ‘‰πŸΎ your answer here] +1) Feedback on our ERD (especially ratings aggregation and route normalization). +2) Best practices for performant server-side filtering & pagination in Postgres (indexes, JOIN patterns). +3) UI/UX guidance for an accessible modal (focus trap, keyboard nav) and filter a11y (ARIA patterns). +4) Deployment pointers for Render (service health checks, environment variables for DB). +If time allows, advice on safely adding a map view (stretch) later. diff --git a/planning/user_stories.md b/planning/user_stories.md index 1e55ecbcd..97734aad5 100644 --- a/planning/user_stories.md +++ b/planning/user_stories.md @@ -1,13 +1,21 @@ -# User Stories +# User Stories (Roles: Passenger, Driver, Admin) -Reference the Writing User Stories final project guide in the course portal for more information about how to complete each of the sections below. +## Passenger +1. As a passenger, I want to search rides by origin and destination so I can find relevant options. +2. As a passenger, I want to filter by date and time so I see only rides I can take. +3. As a passenger, I want to filter by available seats so I don’t request full rides. +4. As a passenger, I want to sort rides by price or time so I can choose the best option. +5. As a passenger, I want a quick-view modal with driver details so I can decide fast without leaving the page. +6. As a passenger, I want to join or leave a ride and instantly see updated seat counts. +7. As a passenger, I want to rate the driver after a completed ride to help others. +8. As a passenger, I want to save favorite routes (e.g., Campus ↔ Airport) for faster searches. -## Outline User Roles +## Driver +9. As a driver, I want to offer a ride with route, time, seats, and price so passengers can join. +10. As a driver, I want to edit or cancel my ride to handle changes. +11. As a driver, I want to see who joined my ride so I can coordinate pickup. +12. As a driver, I want clear validation errors when my form is invalid (e.g., past date). -[πŸ‘‰πŸΎπŸ‘‰πŸΎπŸ‘‰πŸΎ Include at least at least 1, but no more than 3, user roles.] - -## Draft User Stories - -[πŸ‘‰πŸΎπŸ‘‰πŸΎπŸ‘‰πŸΎ Include at least at least 10 user stories in this format:] - -1. As a [user role], I want to [what], so that [why]. +## Admin +13. As an admin, I want to reset the database to default data for testing and demo purposes. +14. As an admin, I want to monitor facet counts (rides per route/date) to ensure data quality.