🌉 NeighborBridge AI

Turn proximity into meaningful connection.

NeighborBridge AI is a community connection engine for Philadelphia. It's not social media — it's a real-world discovery tool that helps people find nearby people, upcoming events, and community organizations based on who they actually are.

---

The Problem

People move to new cities, change neighborhoods, or transition into new phases of life — and they end up isolated despite being surrounded by thousands of potential connections. The tools that exist for meeting people (social media, apps, nextdoor) either require existing networks, feel unsafe, or are too shallow to surface meaningful common ground.

Philadelphia in particular is a city of dense, distinct neighborhoods with rich cultural fabric — but that fabric is invisible to newcomers and underconnected residents.

---

The Solution

NeighborBridge AI takes three inputs — your location, interests, and goal — and uses AI to return:

1. A Shared Ground Insight: A warm, AI-generated paragraph about the common ground you share with people nearby, specific to your identity and Philadelphia neighborhood
2. 3 "People Like You" profiles: Real archetypes of people in your neighborhood who share your background, culture, and interests
3. 3 Upcoming Events: Relevant local events matched to your interests and goals
4. 2 Community Groups: Organizations and collectives where you'd find genuine belonging

---

How the AI Works

The app uses OpenAI's GPT-4o via the Chat Completions API.

The system prompt instructs the model to:

• Interpret the user's identity and intent, not just keywords
• Select people, events, and groups from the mock data that reflect genuine human chemistry
• Write a personalized "Shared Ground Insight" that is emotionally resonant and Philadelphia-specific
• Return structured JSON with sharedGroundInsight, peopleNearby, events, and communityGroups

The model is called with response_format: json_object to guarantee structured output.

Fallback behavior: If no valid OpenAI API key is provided, the backend automatically falls back to a curated mock response so the app is still fully demoable without an API key.

---

What's Mocked vs Real

Feature	Status
User input (location, interests, goal)	✅ Real
OpenAI AI recommendations	✅ Real (needs API key)
People profiles	🟡 Mocked archetypes (10 Philadelphia residents)
Events	🟡 Mocked (10 real-ish Philly events)
Community groups	🟡 Mocked (8 real-ish Philly orgs)
Authentication	❌ None (by design)
Database	❌ None — JSON files only
Map panel	❌ Stretch goal not implemented

---

Project Structure

NeighborBridge/
├── backend/
│   ├── data/
│   │   ├── people.json          # 10 Philadelphia resident archetypes
│   │   ├── events.json          # 10 upcoming Philly events
│   │   └── communityGroups.json # 8 Philly community organizations
│   ├── routes/
│   │   └── match.js             # POST /api/match — AI recommendation engine
│   ├── server.js                # Express server
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── LandingPage.jsx       # Hero, problem statement, how it works
│   │   │   ├── InputForm.jsx         # Location, interests, background, goal
│   │   │   ├── ResultsDashboard.jsx  # Full results layout
│   │   │   ├── SharedGroundInsight.jsx
│   │   │   ├── PeopleCard.jsx
│   │   │   ├── EventCard.jsx
│   │   │   ├── CommunityGroupCard.jsx
│   │   │   └── LoadingSkeleton.jsx
│   │   ├── App.jsx              # Screen state: landing → form → results
│   │   ├── main.jsx
│   │   └── index.css
│   ├── index.html
│   ├── package.json
│   ├── vite.config.js           # Proxies /api to Express backend
│   └── tailwind.config.js
├── .env.example
└── README.md

---

Running Locally

1. Clone and set up environment

cd NeighborBridge

# Copy the example env file
cp .env.example .env

# Add your OpenAI key to .env
# OPENAI_API_KEY=sk-...
# (Without a key, the app falls back to mock recommendations — still fully demoable)

2. Start the backend

cd backend
npm install
npm run dev
# Server starts at http://localhost:3001

3. Start the frontend (new terminal)

cd frontend
npm install
npm run dev
# App starts at http://localhost:5173

4. Open the app

Visit http://localhost:5173

The Vite dev server proxies all /api requests to the Express backend automatically.

---

Tech Stack

Layer	Technology
Frontend	React 18 + Vite
Styling	Tailwind CSS v3
Backend	Node.js + Express
AI	OpenAI GPT-4o (Chat Completions)
Data	Local JSON mock files
No database	JSON-only, no persistence

---

Future Roadmap (beyond hackathon MVP)

• Real event data via Eventbrite / Meetup APIs
• Real community org directory via Google Places or curated database
• Map panel with neighborhood pins
• User-generated connection requests (with safety layers)
• "Community pulse" — live neighborhood activity feed
• Support for other cities beyond Philadelphia

---

Built for a hackathon · Philadelphia, 2025 NeighborBridge AI — turning proximity into meaningful connection.