Neighbourly - Hackathon Build (Stage 1)

Overview

Neighbourly is a hyper-local marketplace that lets providers publish services and seekers book time slots. Stage 1 delivers a single-neighborhood MVP with local JSON persistence, role-aware UI, and core booking validation.

Stage 1 Scope (Delivered)

• Users (provider/seeker) with verification flag.
• Service listings with time slots.
• Booking requests with slot locking and cancellation.
• Local JSON storage on the backend.
• REST API + frontend integration.

Stage 2 Scope (Delivered)

• Postgres-backed data model with H3 geo indexing.
• Auth + RBAC (member vs moderator) with JWTs.
• Radius-based discovery filters + advanced query filters.
• Request throttling across API routes.

Stage 3 Scope (Delivered)

• WebSocket-based realtime messaging with Redis pub/sub.
• Redis caching for high-traffic service discovery.
• Audit logging for critical actions.
• Moderator dashboard endpoints and UI.

Tech Stack

• Frontend: React (JSX) + Zustand + Framer Motion + Lenis
• Backend: Node.js + Express
• Storage: Stage 1 local JSON, Stage 2 Postgres

Folder Structure

backend/
  data/
  docs/
  src/
    controllers/
    routes/
    services/
    utils/
frontend/
  src/
    api/
    components/
    store/
    styles/

Data Model (Stage 1)

• User: { id, name, role, verified, createdAt }
• Service: { id, providerId, title, category, description, price, slots[], createdAt }
• Slot: { id, start, end, available }
• Booking: { id, serviceId, seekerId, slotId, status, createdAt }

Design Decisions

• JSON storage keeps Stage 1 lightweight while mirroring collection-based data access for an easy migration to SQL.
• Controllers + routes separate business rules (e.g., booking validation) from HTTP plumbing.
• Zustand provides a single source of truth for the MVP UI without introducing heavy state frameworks.

Evolution Rationale (Stage 1 ? Stage 3)

• services/db.js abstracts persistence, making it straightforward to swap in a database layer.
• Roles and slot availability rules are centralized so adding auth, RBAC, and real-time updates later is isolated.
• API endpoints already align with future filtering + messaging expansion in Stage 2/3.

Assumptions

• Stage 1 does not require authentication; users are selected from a list.
• Slots are defined by providers at creation time; seekers can only book a listed slot.

Setup

Backend

cd backend
npm install
npm run dev

Server runs at http://localhost:4000.

Frontend

cd frontend
npm install
npm run dev

App runs at http://localhost:5173.

If needed, add a .env file using frontend/.env.example to point at the API.

Stage 2 Setup

Follow STAGE2_SETUP.md to configure Postgres, JWT secrets, and H3 settings.

Stage 3 Setup

Follow STAGE3_SETUP.md to configure Redis, WebSockets, and audit logging.

Stage 1 Test Flow (Manual)

1. Create two users: one provider, one seeker.
2. Select the provider and publish a service with a slot.
3. Select the seeker and book the slot from the marketplace.
4. Verify the slot shows as taken and appears in bookings.
5. Cancel the booking and verify the slot is available again.

API Documentation

See backend/docs/api.md.