v2.0.0 · A self-hostable web platform that helps communities share resources and coordinate during crises — including when the internet is gone.

Vision | Dual-State Architecture | Tech Stack | Quick Start | System Requirements | Project Structure | Offline-First Mesh | API | Roadmap | Telegram Bot | Contributing | License

Modern neighbourhoods have everything they need — the problem is that resources sit idle in individual households. NeighbourGood makes it easy to share tools, vehicles, equipment, food, and skills within a community, reducing waste and building real connections between neighbours.

But sharing goes beyond convenience. When a crisis hits — a flood, a power outage, a pandemic — the same network that shared a drill last Tuesday becomes a lifeline. NeighbourGood's dual-state architecture switches the platform from everyday comfort mode into emergency coordination mode with a single action.

The default mode focuses on community building and resource sharing:

• Resource Library – List and browse items available for borrowing (tools, vehicles, electronics, furniture)
• Skill Exchange – Offer and request skills (tutoring, repairs, cooking, languages)
• Calendar Booking – Reserve items with date/time slots
• Community Events – Organise and RSVP to local events (repair cafés, workshops, seed swaps, meetups)
• Trust & Reputation – Earn reputation points, collect trust badges (Reliable Borrower, Trusted Lender, Skilled Helper), review skills and lending experiences, public user profiles
• Community Feed – Updates, requests, offers in a neighbourhood timeline

Activated by an admin or community vote when an emergency occurs:

• Low-Bandwidth UI – Text-based, high-contrast, no heavy images
• Essential Resources Focus – Food stocks, water filters, generators, medical supplies
• Emergency Ticketing – Replace booking with Request / Offer / Emergency Ping
• Neighbourhood Leaders – Pre-defined coordinators who can triage and assign
• Offline-First – PWA with local caching, BLE mesh networking for internet-free crisis coordination

Docker Compose starts three containers: PostgreSQL database, Python/FastAPI backend, and SvelteKit frontend. Everything is wired together automatically.

Prerequisites: Docker 24+ and the Compose v2 plugin (docker compose — note: no hyphen).

# 1. Clone the repository
git clone https://github.com/neighbourgood/neighbourgood.git
cd neighbourgood

# 2. Create your config file from the template
cp .env.example .env

# 3. Generate a secret key — the app refuses to start without one
echo "NG_SECRET_KEY=$(openssl rand -hex 32)" >> .env

# 4. Build images and start all services (first run takes ~2–3 min)
docker compose up --build

Once you see Application startup complete in the backend logs, the stack is ready:

First time? Navigate to http://localhost:3800, click Sign Up, create an account, then go through the onboarding flow to create or join a community.

--

# Start in the background (detached mode)
docker compose up --build -d

# Stream logs while running in the background
docker compose logs -f

### Local Development

# Stop everything (data is preserved in the postgres volume)
docker compose down

# Stop and wipe ALL data (fresh start)
docker compose down -v

# Rebuild a single service after a code change
docker compose up --build backend

# Apply Alembic migrations on a running stack
docker compose exec backend alembic upgrade head

git pull
docker compose up --build -d

Use this when you want fast hot-reload and don't need a full Postgres instance. The backend defaults to SQLite.

Backend — runs on http://localhost:8300

cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# NG_DEBUG=true allows the default secret key and uses SQLite
NG_DEBUG=true uvicorn app.main:app --reload --port 8300

Frontend — runs on http://localhost:5173

cd frontend
npm install
npm run dev

The Vite dev server automatically proxies /api/* requests to the backend at :8300, so you only need to open http://localhost:5173 in your browser.

A $5–6/month VPS (e.g. Hetzner CX11, DigitalOcean Basic) is sufficient for a small community (< 200 users). PostgreSQL runs inside Docker — no separate DB server needed.

The smart matching engine and Telegram AI assistant support an optional LLM backend (Ollama or any OpenAI-compatible API). If you want to run AI locally:

Recommended model for low-resource hosts: llama3.2:3b via Ollama. See TELEGRAM_SETUP.md for configuration. Without a local LLM configured, all features remain available — AI re-ranking simply falls back to rule-based matching.

neighbourgood/
├── backend/
│   ├── app/
│   │   ├── main.py            # FastAPI application entry point
│   │   ├── config.py           # Settings and environment config
│   │   ├── database.py         # SQLAlchemy database setup
│   │   ├── dependencies.py     # Auth dependencies (get_current_user)
│   │   ├── models/             # SQLAlchemy models (User, Resource, Booking, Message, Community)
│   │   ├── routers/            # API route handlers
│   │   ├── schemas/            # Pydantic request/response schemas
│   │   └── services/           # Business logic (auth, JWT, email notifications)
│   ├── alembic/                # Database migrations
│   ├── tests/                  # Backend tests
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── routes/             # SvelteKit pages
│   │   ├── lib/                # Shared components, API client, stores
│   │   └── app.css             # Global styles (Blue/Red Sky themes)
│   ├── static/                 # Static assets and PWA manifest
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml          # One-command deployment
├── .env.example                # Configuration template
├── CHANGELOG.md
└── README.md

When the internet goes down, NeighbourGood keeps working. In Red Sky mode the web app can connect to a nearby native BitChat node over Bluetooth Low Energy (BLE) and relay crisis data — emergency tickets, votes, pings — through the mesh without any internet connectivity at all.

┌──────────────────────────────────────────────────────────────────────┐
│                         INTERNET DOWN                                │
└──────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────┐        ┌────────────────────────────────┐
  │   NeighbourGood         │        │   NeighbourGood                │
  │   Web App (Chrome)      │        │   Web App (Chrome)             │
  │                         │        │                                │
  │  [Connect to Mesh] btn  │        │  Receives mesh tickets         │
  │  Status: ● Connected    │        │  with "via BLE mesh" badge     │
  └──────────┬──────────────┘        └──────────────┬─────────────────┘
             │ Web Bluetooth (1 GATT connection)     │ Web Bluetooth
             │                                       │
  ┌──────────▼──────────────┐        ┌──────────────▼─────────────────┐
  │  BitChat Native Node    │        │  BitChat Native Node           │
  │  (iOS / Android)        │        │  (iOS / Android)               │
  │                         │        │                                │
  │  Acts as BLE relay      ◄────────►  Acts as BLE relay             │
  │  Handles mesh routing   │  BLE   │  Handles mesh routing          │
  │  Multi-hop, up to 7 hops│  Mesh  │  Store-and-forward             │
  └──────────┬──────────────┘        └──────────────┬─────────────────┘
             │                                       │
             └──────────────────┬────────────────────┘
                                │
             ┌──────────────────▼────────────────────┐
             │  More BitChat nodes in the            │
             │  neighbourhood — no limit on count    │
             │  or distance (up to 7 hops / ~700m)   │
             └───────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────────────┐
  │                    INTERNET RETURNS                              │
  │                                                                  │
  │  NeighbourGood shows "Sync N messages" button                    │
  │  POST /mesh/sync  →  server deduplicates by message UUID         │
  │  Emergency tickets and votes appear on the server                │
  └──────────────────────────────────────────────────────────────────┘

Every NeighbourGood crisis action (create ticket, cast vote) is wrapped in a small JSON envelope and encoded as a standard BitChat broadcast message:

{
  "ng": 1,
  "type": "emergency_ticket",
  "community_id": 42,
  "sender_name": "Alice",
  "ts": 1741910400000,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "title": "Need drinking water — north block",
    "ticket_type": "request",
    "urgency": "critical"
  }
}

Native BitChat apps relay this message through the mesh without needing to understand its contents. Other NeighbourGood web clients receive it and display it immediately with a "via BLE mesh" badge.

Requirements: Chrome or Edge (desktop or Android). Web Bluetooth is not available in Firefox or Safari. A nearby device running the native BitChat app is required.

1. Switch your community to Red Sky mode — the mesh panel only appears during crises.
2. Open the Emergency (Triage) page in Chrome.
3. Click "Connect to Mesh" — Chrome shows a device picker listing nearby BitChat nodes.
4. Select a node — the status dot turns green and peer count appears.
5. Create emergency tickets offline — the form button becomes "Broadcast via Mesh". Your ticket travels through the BLE mesh to other NeighbourGood users.
6. When internet returns — click "Sync N messages" to push mesh-received data to the server. The server deduplicates by message UUID so re-syncing is safe.

See API_ENDPOINTS.md for the full endpoint reference. Interactive docs at /docs when the backend is running.

• Project scaffold (FastAPI + SvelteKit + Docker)
• /status endpoint with dual-mode indicator
• Blue Sky / Red Sky CSS theme system
• User registration and authentication (JWT)
• User profiles with neighbourhood assignment
• Basic resource listing (CRUD for items)
• Resource detail page
• SQLite database with Alembic migrations

• Resource categories (tools, vehicles, electronics, furniture, food, clothing)
• Image upload for resources
• Search and filter resources
• Calendar-based booking system
• Request/approve flow for borrowing
• User messaging (in-app)
• Email notifications

• Skill exchange listings (offer/request with 10 categories)
• Reputation/trust score system (computed from activity, 5 levels)
• Community feed / activity timeline (auto-generated from events)
• Community events — create, browse, RSVP; 9 categories, upcoming filter, max-attendee cap (v1.8.0)
• Neighbourhood groups (Hybrid: PLZ-based with custom names)
• Community merge function with auto-suggestions
• Onboarding flow (search/join/create community)
• Community-scoped resources (soft scoping with community_id)
• Instance identity and /instance/info endpoint (federation prep)
• PostgreSQL production default (Docker Compose)
• Invite system for new members (code-based, with expiry/max uses)
• Rating and review system for transactions (1-5 stars, per-booking)
• Skill reviews & endorsements — community members can rate skill providers (v2.0.0)
• Trust badges — Reliable Borrower, Trusted Lender, Skilled Helper (v2.0.0)
• Public user profile page with trust summary, badges, and paginated reviews (v2.0.0)

• Instance metadata with admin accountability (name, region, contact)
• /instance/info public endpoint for directory crawling
• Instance directory (discover other NeighbourGood instances)
• Cross-instance Red Sky alerts
• User data export (portable backup)
• Instance migration tooling

• Admin toggle for crisis mode (per-community)
• Community vote mechanism for mode activation (60% threshold)
• Emergency ticketing system (Request / Offer / Emergency Ping)
• Neighbourhood leader roles and assignment
• Explore page with community map for unregistered users
• Low-bandwidth UI variant (text-only, image-free mode)
• Essential resource inventory tracking (quantity-based stock management)
• Priority-based ticket triage (triage dashboard for leaders/admins)

• Password strength validation (min 8 chars, uppercase + lowercase + digit)
• Email format validation (EmailStr)
• Security response headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, HSTS)
• Secret key validation (reject default key in production, require 32+ chars)
• File upload hardening (magic byte validation, extension sanitisation)
• Input length limits on all user-facing schemas

• Rate limiting on auth endpoints (login, register) — 5 req/min; general 60 req/min; uploads 10 req/min (v1.7.0)
• Account lockout after repeated failed login attempts — 5 failures in 15 min → 15-min lockout (v1.7.0)
• CSRF protection for state-changing operations — Origin + X-CSRF-Token validation (v1.7.0)
• Session invalidation on password change
• Audit logging for admin actions

• Field-level encryption for sensitive data (email, messages)
• Automated database backups with encryption at rest
• PII anonymisation for deleted accounts
• Content Security Policy tuning per route
• Dependency vulnerability scanning (CI integration)

• Full PWA with service worker caching (v0.9.9)
• Offline item browsing and request queuing (v1.1.0)
• Background sync when connectivity returns (v1.1.0)
• Data export and backup tools (v1.1.0)
• BLE mesh gateway for internet-free crisis coordination (v1.2.0)

• TLS certificate automation (Let's Encrypt)
• Container image scanning and hardening
• Network segmentation (backend ↔ database)
• Secrets management (Vault / sealed secrets)
• Incident response runbook

• Smart matching with AI enhancement (v1.5.0) — rule-based skill/resource matching + optional Ollama/OpenAI re-ranking
• Mesh networking (BitChat BLE gateway) (v1.2.0) — offline crisis comms via Bluetooth mesh
• Decentralized data sync between instances (v1.4.0) — pull-based federation sync with public snapshot endpoint, incremental cursors, and federated resource/skill browsing
• Federation explorer UI (v1.9.0) — instance directory browser, federated resource/skill pages, cross-instance alert banners, enriched instance stats
• Enhanced BLE mesh networking (v1.9.5) — 10-phase overhaul: mesh dashboard, auto-sync, resource sharing, check-ins, multi-hop relay, E2E encryption, analytics
• Multi-language support (i18n) (v1.1.0) — 12 languages with RTL support
• Community events (v1.8.0) — create, browse and RSVP to local events (repair cafés, workshops, seed swaps, meetups); 9 categories, max-attendee cap, upcoming filter, full-text search
• Admin dashboard with analytics
• Outbound webhook system with HMAC-SHA256 signing (generic integrations)
• Telegram bot integration (personal notifications, community group alerts, bot commands) + AI natural language interface (v1.6.0)
• Signal integration
• Matrix integration

NeighbourGood includes a Telegram bot with an AI-powered natural language interface — members can search resources, find skills, and coordinate during crises directly from Telegram without opening the app.

See TELEGRAM_SETUP.md for the full setup guide, including:

• Creating and configuring your bot
• Linking personal accounts and community groups
• Setting up local AI with Ollama (model recommendations included)
• What the agent can and cannot do
• Slash command reference and notification event table

To customise the agent's behaviour, tone, or available intents, see TELEGRAM_AGENT.md.

This project is in its early stages. Contributions, ideas, and feedback are welcome.

See LICENSE for details.