Skip to content

README.md

Latest commit

 

History

History
446 lines (336 loc) · 15.2 KB

README.md

File metadata and controls

446 lines (336 loc) · 15.2 KB

Solarpunk Gift Economy Mesh Network 🌱

Production-ready system for regenerative communities to coordinate mutual aid without internet dependency.

Status License Python TypeScript

📱 Android App

Download APK

Standalone offline app - runs Python backend directly on your phone. No internet required after install.

  • Works 100% offline
  • 67 MB download
  • Android 8.0+ required
  • Mesh sync via WiFi Direct

View all releases

🚀 One-Line Install

Linux/Mac:

curl -sL https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

Termux (Android):

pkg install curl -y && curl -sL https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

Or using wget:

wget -qO- https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

Note: Requires Python 3.11 (not 3.12). The setup script will automatically install Python 3.11 if needed. See PYTHON_VERSION.md for details.

This installs everything and starts all services. Access at http://localhost:3000 when complete.

Running on Android (Termux)

Prerequisites

  • Android 7.0+ (Android 11+ requires extra steps below)
  • 2GB+ free storage
  • Stable WiFi connection

Installation Steps

  1. Install Termux from F-Droid (NOT Google Play - that version is broken)

    • Install F-Droid app: https://f-droid.org/
    • Search for "Termux" in F-Droid
    • Install Termux (version 0.118.x recommended)

  2. Grant Permissions (IMPORTANT for Android 11+)

    • Open Android Settings → Apps → Termux → Permissions
    • Enable "Files and media" or "Storage"
    • For Android 11+: Enable "All files access" under Special app access

  3. First Launch

    • Open Termux
    • Wait for bootstrap installation (2-5 minutes)
    • Do not touch anything until you see a $ prompt
    • If you get "Permission denied" errors, see troubleshooting below

  4. Run the installer:

    pkg install curl -y && curl -sL https://raw.githubusercontent.com/lizTheDeveloper/solarpunk_utopia/main/setup.sh | bash

    Installation takes 5-15 minutes depending on your device.

  5. Access the app in your phone's browser:

    # Open Chrome/Firefox and go to:
http://localhost:3000

  6. Keep services running after closing Termux:

    Prevent CPU sleep (required):

    termux-wake-lock

    This keeps services running even when screen is off.

    Start services in background:

    nohup ./run_all_services.sh > /dev/null 2>&1 &

    Prevent Android from killing Termux:

    • Settings → Apps → Termux → Battery → Unrestricted (or "Don't optimize")
    • This prevents Android from killing Termux in the background

    Keep screen on while working (optional, drains battery):

    • Settings → Display → Screen timeout → 30 minutes (or higher)
    • Or use Developer Options → Stay awake (while charging)

  7. Auto-start on phone boot (optional):

    • Install Termux:Boot from F-Droid
    • Create startup script: 
      mkdir -p ~/.termux/boot
cat > ~/.termux/boot/start-solarpunk.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/sh
termux-wake-lock
cd ~/solarpunk_utopia
./run_all_services.sh > /dev/null 2>&1 &
EOF
chmod +x ~/.termux/boot/start-solarpunk.sh

  8. Check service health:

    curl http://localhost:8000/health

Troubleshooting Android Installation

"Unable to install bootstrap" or "Permission denied":

  1. Clean reinstall (this fixes 90% of issues):

    # In Android Settings:
Settings → Apps → Termux → Storage → Clear Data
Settings → Apps → Termux → Uninstall

# Then reinstall from F-Droid and grant permissions immediately

  2. Android 11+ Phantom Process Issue:

    • If bootstrap keeps failing, you may need to disable phantom process killer
    • Requires ADB: adb shell "settings put global settings_enable_monitor_phantom_procs false"
    • Then reboot phone and reinstall Termux

  3. Change repository mirror:

    termux-change-repo
# Select "All repositories" → Choose a different mirror

  4. Alternative: Use UserLAnd

    • If Termux won't work, install UserLAnd from Play Store/F-Droid
    • Choose Ubuntu distribution
    • Run the Linux installer instead

Services won't start:

  • Make sure you have enough storage (check with df -h)
  • Try killing existing processes: ./stop_all_services.sh then restart

Can't access localhost:3000:

  • Check if services are running: ps aux | grep python
  • Check logs: tail -f logs/dtn_bundle_system.log
  • Make sure you're using http:// not https://

What is This?

A complete offline-first mesh network system for Solarpunk communes to:

  • 🎁 Share resources via gift economy (offers, needs, exchanges)
  • 📦 Distribute bundles via delay-tolerant networking
  • 🔍 Search distributed indexes across mesh islands
  • 📚 Share knowledge through chunked file distribution
  • 🤖 Get AI assistance for matching, planning, and coordination
  • 🌐 Operate autonomously without internet or corporate platforms

This is not a demo. This is production software for real communities.

Quick Start

Manual Setup (if you prefer not to use the one-liner above)

# Clone repository
git clone https://github.com/lizTheDeveloper/solarpunk_utopia.git
cd solarpunk_utopia

# Setup backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Start all services
./run_all_services.sh

# Start frontend (new terminal)
cd frontend
npm install
npm run dev

# Access at http://localhost:3000

See QUICKSTART.md for detailed guide.

What's Included

Core Systems (28 of 31 complete - 90%)

TIER 0 - Foundation

  • ✅ DTN Bundle System (5 systems) - Delay-tolerant networking with store-and-forward
  • ✅ ValueFlows Node (6 systems) - Complete gift economy coordination (VF v1.0)
  • ⏳ Phone Deployment (0 systems) - Deferred for physical hardware

TIER 1 - Core Functionality

  • ✅ Discovery & Search (3 systems) - Distributed queries across mesh
  • ✅ File Chunking (3 systems) - Knowledge distribution with Merkle trees
  • ✅ Multi-AP Mesh Network (4 systems) - Physical infrastructure (Mode A/C)

TIER 2 - Intelligence

  • ✅ Agent System (7 systems) - AI agents for coordination (proposals require approval)

Infrastructure

  • ✅ Complete unified frontend (React + TypeScript, 47 files)
  • ✅ Systemd service management (Linux)
  • ✅ Nginx reverse proxy
  • ✅ End-to-end integration tests
  • ✅ Comprehensive documentation (8,000+ lines)

Statistics

  • 235+ source files
  • 32,000+ lines of production code
  • 90+ REST API endpoints (auto-documented)
  • 20+ test suites (100% pass rate)

Key Features

🎁 Gift Economy Coordination

  • Create offers and needs in <1 minute
  • AI matchmaker finds compatible offers/needs
  • Exchange coordination with bilateral approval
  • Event recording for accountability and provenance
  • All 13 ValueFlows object types implemented

📦 Delay-Tolerant Networking

  • Store-and-forward between AP islands
  • Priority-based forwarding (emergency → perishable → normal → low)
  • Ed25519 cryptographic signing
  • TTL enforcement and cache budgets
  • Bundle propagation <10 min via bridge nodes

🔍 Distributed Discovery

  • Periodic index publishing (offers, needs, files, services)
  • Query propagation through mesh network
  • Cached indexes enable offline discovery
  • Bridge nodes serve as query responders

📚 Knowledge Distribution

  • Content-addressed file distribution (SHA-256)
  • Intelligent chunking (256KB-1MB)
  • Merkle tree verification
  • Library nodes cache popular content
  • Resume partial downloads

🌐 Multi-AP Mesh Infrastructure

  • Multiple AP islands with independent subnets
  • Bridge nodes walk between islands carrying bundles
  • Mode C (DTN-only) always works (mandatory)
  • Mode A (BATMAN-adv) optional speedup
  • Graceful degradation

🤖 AI Coordination Agents

  • 7 specialized agents (matchmaker, scheduler, planner, etc.)
  • Proposal-based (NOT allocations) - human approval required
  • Completely opt-in (no surveillance)
  • Transparent reasoning (explanation + inputs + constraints)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Solarpunk Mesh Network                    │
└─────────────────────────────────────────────────────────────┘

┌──────────────────┐
│  DTN Bundle      │  ← Foundation: Store-and-forward transport
│  System          │     Port 8000, Ed25519 signing
│  (TIER 0)        │
└────────┬─────────┘
         │
         ├─────────┐
         ↓         ↓
┌──────────────┐  ┌──────────────┐
│ ValueFlows   │  │ Discovery &  │  ← Core: Economic coordination
│ Node         │  │ Search       │     and distributed search
│ (TIER 0)     │  │ (TIER 1)     │
│ Port 8001    │  │ Port 8003    │
└──────────────┘  └──────────────┘
         │              │
         ├──────────────┼─────────┐
         ↓              ↓         ↓
┌──────────────┐  ┌─────────┐  ┌──────────────┐
│ Agent System │  │  File   │  │  Multi-AP    │
│ (TIER 2)     │  │ Chunking│  │  Mesh        │
│ 7 AI agents  │  │(TIER 1) │  │  (TIER 1)    │
│              │  │Port 8004│  │  Port 8002   │
└──────────────┘  └─────────┘  └──────────────┘

Documentation

Getting Started

System Details

  • BUILD_PLAN.md - Vision, architecture, and specifications
  • FINAL_SUMMARY.md - Complete summary of what was built
  • Component READMEs - Each system has detailed documentation

API Documentation

Auto-generated interactive docs available at:

Technology Stack

Backend: Python 3.12, FastAPI, SQLite, asyncio, Ed25519 crypto Frontend: React 18, TypeScript, Vite, Tailwind CSS, React Query Infrastructure: Systemd, Nginx, Python venv Mesh: BATMAN-adv, hostapd, dnsmasq Testing: pytest, pytest-asyncio

Use Cases

For Solarpunk Communes

  • Share surplus food before it spoils (perishables dispatcher)
  • Lend tools and equipment easily (offer/need matching)
  • Coordinate seasonal planting and harvests (permaculture planner)
  • Teach and learn skills within community (education pathfinder)
  • Plan work parties and events (scheduler agent)
  • Track resource flows for accountability (event recording)
  • Operate entirely offline and autonomously (DTN networking)

For Developers

  • Complete reference implementation of ValueFlows v1.0
  • Production-ready DTN bundle system with Ed25519 signing
  • Multi-agent AI coordination framework with approval gates
  • Content-addressed file distribution with Merkle trees
  • Distributed discovery and search across mesh networks
  • Real-world offline-first architecture patterns

Project Structure

solarpunk_utopia/
├── app/                      # DTN Bundle System + AI Agents
├── valueflows_node/          # ValueFlows implementation + React UI
├── discovery_search/         # Discovery & Search system
├── file_chunking/            # File chunking system
├── mesh_network/             # Multi-AP mesh network software
├── frontend/                 # Unified frontend application
├── tests/integration/        # End-to-end tests
├── openspec/                 # OpenSpec proposals (7 proposals)
├── setup.sh                  # One-line installer
├── run_all_services.sh       # Start all services
└── stop_all_services.sh      # Stop all services

Contributing

This is infrastructure for regenerative communities. Contributions welcome!

  1. Read CLAUDE.md for repository architecture
  2. Check BUILD_STATUS.md for what's complete
  3. Review openspec/ for proposals and specifications
  4. Run tests: pytest tests/integration/ -v
  5. Follow existing patterns (FastAPI, React Query, Pydantic, TypeScript)

License

MIT License - Use this to build a better world!

See LICENSE file for details.

Vision

From the original specification:

"We're building the infrastructure for regenerative gift economy communities. This isn't just software—it's a tool for communities to coordinate mutual aid, share resources, plan permaculture work, and learn together, all without depending on corporate platforms or internet infrastructure."

When this system works, communes can:

  • ✅ Share surplus food before it spoils
  • ✅ Lend tools and equipment easily
  • ✅ Coordinate seasonal planting and harvests
  • ✅ Teach and learn skills within the community
  • ✅ Plan work parties and events
  • ✅ Track resource flows for accountability
  • ✅ Operate entirely offline and autonomously

This is infrastructure for a better world. Let's build it together. 🌱

Status

Current: ✅ Production ready (28 of 31 systems complete) Next: Hardware deployment (Raspberry Pi APs, Android bridge nodes) Future: Multi-commune federation via NATS

Support

Built with ❤️ for regenerative gift economy communities

Let's coordinate mutual aid without corporate platforms. Let's build solidarity infrastructure. Let's create the world we want to see. 🌱