ConnectedCommunity MVP

ConnectedCommunity is a mobile-first MERN PWA that helps neighbours verify their address, share updates, chat in real-time, and keep their street organised.

Project structure

client/   # Vite + React + TypeScript PWA
server/   # Express + TypeScript API with MongoDB

Prerequisites

• Node.js 18+
• npm 9+
• MongoDB Atlas cluster (use the provided connection string with the new connectedcommunity_mvp2 database name)

Environment setup

Create .env files for both the API and client using the provided examples.

cp server/.env.example server/.env
cp client/.env.example client/.env

Fill in your own secrets (JWT secret, MongoDB URI, email provider credentials, etc.). Never commit secrets.

Running locally

1. API

   cd server
   npm install
   npm run dev

   The API will start on http://localhost:4000 and log email verification links in development.

2. Client

   cd ../client
   npm install
   npm run dev

   The PWA runs on http://localhost:5173 and will prompt for installation once built.

Seeding demo data

Seed the database with example towns, streets, users, posts, and chat history:

cd server
npm run seed

This creates an admin user (admin@connectedcommunity.uk / Password123) for quick testing.

Key features

• Email registration and verification flow with links sent via Resend (or logged to console in development).
• Address ownership workflow with approvals, transfers, and safeguards for a single active owner per address.
• Street and town feeds with category filters, comments, and lightweight moderation via reports.
• Private conversations and street-level real-time chat using Socket.io (new joiners cannot view messages sent before they joined).
• Admin console for stats, user management, report handling, and address ownership transfers.
• Mobile-first UI with Tailwind CSS, bottom navigation, skeleton states, and safe-area support.
• PWA using vite-plugin-pwa, app-shell caching, and an offline fallback page.

Deployment notes

• Client → Vercel (set VITE_API_BASE to your API URL).
• Server → Render or similar (set environment variables and enable WebSockets).
• Database → MongoDB Atlas (new database name connectedcommunity_mvp2).
• Add real PNG icons (192×192 & 512×512) to client/public/icons/ before publishing the PWA.

Verifying the MVP

1. Register a new user.
2. Copy the verification link from the API logs and open it in the browser.
3. Log in, join your address, and create a post.
4. Open a second account to submit an address request and approve it as the owner.
5. Exchange messages in the street chat and verify new joiners cannot see old messages.
6. Log in as the seeded admin user and review stats, users, and open reports.