SafePath MVP - Local Development Guide

Welcome to the SafePath High-Concurrency Backend MVP! This document provides detailed instructions to boot, test, and interact with your custom microservices architecture completely locally.

🛠 Prerequisites

Ensure your local machine has the following installed:

• Docker & Docker Compose (for Kafka, Zookeeper, Redis, PostgreSQL, and Go Backend)
• Node.js 18+ (for the Vite Frontend)
• Go 1.22+ (optional, if you wish to run the background mock simulator outside of Docker)

---

🚀 1. Booting the Backend Infrastructure

The entire backend is deeply containerized. This includes the AntiGravity Go API, Apache Kafka messaging queue, Redis caching layer, and PostgreSQL persistence.

1. Open your terminal in the root project directory:

   cd /home/varad/Projects/SafePath-MVP

2. Start the cluster:

   docker compose up --build -d

3. To verify everything is running cleanly, check the application logs to see successful connections:

   docker compose logs -f app

(You should see logs indicating Kafka and Postges initialized successfully without errors)

---

🎨 2. Booting the React Frontend

The frontend React client has been updated to sever Supabase endpoints heavily relying on your local backend port 8080.

1. Open a new terminal tab.
2. Navigate to the frontend directory:

   cd /home/varad/Projects/SafePath-MVP/frontend

3. Install dependencies (using the legacy peer deps flag due to Vite module boundaries):

   npm install --legacy-peer-deps

4. Start the Vite development server:

   npm run dev

5. Open your web browser at http://localhost:5173.

---

📡 3. Seeding Mock Traffic (Optional)

To see the application "come alive" with mock users pinging their locations and dynamically rendering simulated Danger Zones offline:

1. Open a new terminal tab.
2. Formally boot the Mock Simulator:

   cd /home/varad/Projects/SafePath-MVP/backend/cmd/seed
   go run main.go

3. Checking back on your frontend, you should immediately witness map pings adjusting coordinates automatically every 3 seconds!

---

✅ 4. Testing End-to-End Functionality

Here are the primary testing phases to ensure your architecture is successfully deployed:

Test A: The Live Mock Danger Zones

• Simply open the dashboard. You should seamlessly observe static fallback "Danger Zones" populated onto the geofence fetched natively from http://localhost:8080/api/v1/dangerzones rather than WebSockets.

Test B: Live User Map Refresh

• With the Simulator daemon running, watch your app console / map for incoming tracking coordinate patches.
• You can cross-reference the success on the backend by watching docker compose logs -f app confirming 200 OK on PATCH /api/v1/location.

Test C: SOS Trigger & Kafka Engine

• Inside the UI on http://localhost:5173, locate the START TRIP / SOS button.
• Click and hold the red SOS button for a continuous exactly 3 seconds.
• The 🚨 EMERGENCY ALERT overlay will immediately trigger.
• Under the hood, this pushed a POST /api/v1/sos payload cleanly routed through Kafka streams natively. Check the backend docker logs to spot the [Twilio Mock] interceptor completing the loop and simulating text alerts!

Enjoy building out the rest of the hackathon!