⚡ RideCast

Ride and Explore with Absolute Certainty

RideCast is a full-stack motorcycle rider companion app that delivers real-time weather safety intelligence, AI-powered briefings, tyre traction analysis, ride logging, and hotspot management — all in a sleek dark-mode interface.

---

🧰 Tech Stack

Frontend

Layer	Technology
Framework	Angular 21
Styling	Tailwind CSS
Maps	Leaflet.js
Language	TypeScript

Backend

Layer	Technology
Runtime	Node.js + TypeScript
Framework	Express.js
Database	MongoDB via Mongoose
AI	Google Gemini API (@google/genai)
Auth	JWT + bcryptjs
Email	Nodemailer

---

✨ Features

• Rider Safety Dashboard — Real-time weather (temp, wind, humidity, rain), Safety Index score (0–100), Tyre Traction & Tarmac temperature analysis, and ride advisory (Safe / Caution / Dangerous).
• Weather Details — Current conditions + 7-day forecast with daily summaries.
• Saved Hotspots — Save favourite riding locations by coordinates. Interactive Leaflet map shows the active hotspot pin. GPS auto-fill supported.
• Rides Logbook — Log rides with title, distance, duration, notes, and hotspot reference. Auto-captures weather snapshot at time of logging.
• Rider AI Advisor — Gemini-powered chat assistant with context-aware answers about road safety, grip, crosswinds, and optimal ride windows. Includes a Safety Briefing tab with a full-page report.
• Warnings & Alerts — Active road hazard alerts fetched for the current hotspot.
• User Auth — Register, login, forgot password, reset password (email flow).
• Profile Management — Update name, email, password, and profile picture.
• Settings — Toggle distance unit (km / mi), temperature unit (°C / °F), and notification preferences.
• Admin Console — Manage users, set system-wide announcements, view visitor stats, send broadcast emails, manage all rides.
• System Announcements — Dynamic banner displayed app-wide when an admin activates an announcement.

---

🗂️ Project Structure

ridecast/
├── src/                        # Angular frontend
│   ├── app/
│   │   ├── components/         # Navbar, Toast, Spinner
│   │   ├── guards/             # auth.guard.ts
│   │   ├── interceptors/       # api.interceptor.ts (JWT + base URL)
│   │   ├── pages/              # All route pages
│   │   │   ├── landing/
│   │   │   ├── login/
│   │   │   ├── register/
│   │   │   ├── forgot-password/
│   │   │   ├── reset-password/
│   │   │   ├── dashboard/
│   │   │   ├── weather/
│   │   │   ├── locations/
│   │   │   ├── rides/
│   │   │   ├── ai-chat/
│   │   │   ├── profile/
│   │   │   ├── settings/
│   │   │   ├── admin/
│   │   │   └── not-found/
│   │   └── services/           # auth, toast, weather, location, ai, settings
│   └── environments/           # environment.ts / environment.development.ts
│
├── backend/                    # Express API
│   └── src/
│       ├── models/             # Mongoose models (User, Ride, Location, etc.)
│       ├── routes/             # API route handlers
│       │   ├── auth.ts         # Register, login, password reset
│       │   ├── dashboard.ts    # Weather + safety data aggregation
│       │   ├── weather.ts      # Forecast endpoints
│       │   ├── locations.ts    # Hotspot CRUD
│       │   ├── rides.ts        # Ride log CRUD
│       │   ├── ai.ts           # Gemini AI chat + briefing
│       │   ├── safety.ts       # Safety index calculation
│       │   ├── admin.ts        # Admin management
│       │   └── health.ts       # Health check
│       ├── middleware/         # Auth middleware, rate limiting
│       ├── services/           # Gemini AI service, weather service
│       └── utils/              # Helpers
│
└── public/                     # Static assets (favicons, icons)

---

🚀 Getting Started

Prerequisites

• Node.js v18+
• MongoDB running locally (mongodb://127.0.0.1:27017)
• Angular CLI v21 (npm install -g @angular/cli)
• Optional: Google Gemini API key for full AI functionality

---

1. Clone the repo

git clone https://github.com/your-username/ridecast.git
cd ridecast

---

2. Setup & Run the Backend

cd backend
npm install

Create a .env file in backend/:

PORT=5000
MONGODB_URI=mongodb://127.0.0.1:27017/ridecast
JWT_SECRET=your_super_secret_jwt_key
GEMINI_API_KEY=your_gemini_api_key
NODE_ENV=development
FRONTEND_URL=http://localhost:4200

# Email (optional — for password reset)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@email.com
SMTP_PASS=your_app_password
SMTP_FROM=RideCast <your@email.com>

Start the dev server:

npm run dev

Backend runs at http://localhost:5000

---

3. Setup & Run the Frontend

# From the project root
npm install
npm start

Frontend runs at http://localhost:4200

The Angular ApiInterceptor automatically rewrites all /api/ calls to http://localhost:5000 in development — no proxy config needed.

---

🔧 Environment Configuration

File	Purpose
src/environments/environment.ts	Production API URL
src/environments/environment.development.ts	Development API URL (http://localhost:5000)

File replacement is configured in angular.json so the correct environment is automatically selected per build configuration.

---

📡 API Endpoints

Method	Endpoint	Description
POST	/api/auth/register	Register new user
POST	/api/auth/login	Login and receive JWT
POST	/api/auth/forgot-password	Send password reset email
POST	/api/auth/reset-password	Reset password with token
GET	/api/dashboard	Aggregated weather + safety data
GET	/api/weather/forecast	7-day weather forecast
GET/POST	/api/locations	Get / save hotspots
DELETE	/api/locations/:id	Delete a hotspot
GET/POST	/api/rides	Get / log rides
DELETE	/api/rides/:id	Delete a ride
POST	/api/ai/chat	Gemini AI chat query
POST	/api/ai/briefing	Generate safety briefing report
GET	/api/safety	Get safety warnings & alerts
GET	/api/health	Server health check
GET/PUT	/api/admin/*	Admin management routes

---

🏗️ Build for Production

# Frontend
npm run build

# Backend
cd backend
npm run build
npm start

---

🤖 AI Mode

When GEMINI_API_KEY is not set, the backend runs in Mock/Demo mode — the AI advisor returns weather-contextual canned responses. Add a valid key from Google AI Studio to enable full Gemini-powered responses.

---

📦 Key Dependencies

Frontend

• @angular/core v21
• leaflet — interactive maps
• rxjs — reactive data streams

Backend

• express — HTTP server
• mongoose — MongoDB ODM
• jsonwebtoken — JWT auth
• bcryptjs — password hashing
• @google/genai — Gemini AI SDK
• nodemailer — transactional email
• helmet + express-rate-limit — security

---

📄 License

MIT