Humanity

Wholesomely aiding humanity's betterment.

An open-source cooperative project to end poverty through education and technology. Not charity — capability. Public domain. Built by volunteers. For everyone.

🌐 united-humanity.us · 💬 Chat · 📦 GitHub · 💜 Discord

What It Is

Humanity is two things built together:

1. HumanityOS — a real-world platform for communication, collaboration, and life management. Chat, DMs, voice calls, project boards, marketplace, skill tracking, inventory, maps. Think of it as an operating system for your life that you actually own.

2. Project Universe — a free game that teaches practical skills (homesteading, agriculture, building, health) by using the same underlying data layer as the real platform. Your in-game skills reflect real-world capability.

Both share the same server, identity system, and data layer. The game is how people learn to use the tools for real.

What's Live

Pages (18 standalone pages at /)

Communication (the core, fully working)

• Channels — admin-created rooms with descriptions and categories
• E2E encrypted DMs — ECDH P-256 + AES-256-GCM, server never sees plaintext
• Threaded replies — reply to any message with collapsible threads
• Voice channels — persistent, always-on WebRTC mesh rooms
• 1-on-1 video calls — WebRTC peer-to-peer with audio, video, screen share, PiP
• @mentions, emoji reactions, message editing, message search
• Image sharing with lazy-loaded placeholders
• Browser push notifications and 6 notification sound options
• Typing indicators and unread markers

Identity & Privacy

• Ed25519 cryptographic identity — keys stored in your browser, never on server
• Multi-device key linking — same identity across devices
• Device management — list, label, and revoke linked keys
• Key backup, export, and import
• Encrypted user data sync — settings, follows, profile encrypted at rest
• No IP logging, no analytics, no tracking

Social

• Follow/friend system — mutual follow = friends, friends unlock DMs
• Friend codes — 8-character codes with 24-hour expiry, auto-mutual-follow
• User profiles with bio, pronouns, location, website, privacy controls
• Unique pixel-art identicons per user
• Groups — private group conversations
• Client-side user blocking and report system

Productivity Tools

• Project board — kanban-style with visible task IDs
• Marketplace — peer-to-peer listings, kiosks, donation pricing presets
• Asset library — file upload, browse, tag, preview
• 118-element catalog, 44 materials, processing chains
• Browse directory — 52 curated sites with uptime pings and domain info
• Dashboard — 10 widget types, customizable layout
• Notes, Todos, Garden tracker

Platform

• PWA installable — works on mobile, add to homescreen
• Desktop app — Tauri v2 for Windows, macOS, Linux
• Command palette — quick navigation
• Dark/light themes, accent colors, font size controls
• Auto-reload on deploy — no manual refresh needed

Moderation & Federation

• Role-based: admin 👑, mod 🛡️, verified ✦, donor 💎
• Kick/ban, invite codes, auto-lockdown when no mods online
• Phase 1 federation — anyone can host; servers discover each other
• Single binary, zero dependencies, under 10 minutes to self-host
• Verified servers that adopt the Humanity Accord earn highest trust

Architecture

Codebase Structure

Humanity/
├── crates/
│   └── humanity-relay/        ← Rust WebSocket relay server
│       ├── src/
│       │   ├── main.rs        ← Entry point, routing, axum setup
│       │   ├── relay.rs       ← WebSocket handler (~5600 lines, message routing)
│       │   ├── handlers/      ← Extracted relay helpers
│       │   │   ├── broadcast.rs   broadcast_peer_list, broadcast_channel_list, etc.
│       │   │   ├── federation.rs  server-to-server connections
│       │   │   └── utils.rs       is_private_ip, fetch_link_preview, html_decode, etc.
│       │   ├── storage/       ← SQLite domain modules
│       │   │   ├── mod.rs     Storage struct, open(), schema migrations
│       │   │   ├── messages.rs, channels.rs, dms.rs, social.rs, profile.rs
│       │   │   ├── reactions.rs, pins.rs, marketplace.rs, streams.rs
│       │   │   └── board.rs, assets.rs, skill_dna.rs, misc.rs, uploads.rs
│       │   └── api.rs         ← HTTP REST API endpoints
│       └── client/            ← Web client (no build step)
│           ├── index.html     ← Chat page — loads all scripts in order
│           ├── app.js         ← Core: state, connect, handleMessage, switchChannel
│           ├── chat-messages.js   reactions, editing, pins, typing, threads
│           ├── chat-dms.js        DM state and conversation list
│           ├── chat-social.js     follow/friend system, groups
│           ├── chat-ui.js         notifications, sidebar, search, commands
│           ├── chat-voice.js      voice rooms, 1-on-1 calls, video, sidebar
│           ├── chat-profile.js    profile edit/view modals
│           ├── chat-p2p.js        P2P contact cards, WebRTC DataChannel
│           ├── crypto.js          Ed25519/ECDH/AES helpers
│           ├── base.css, layout.css, sidebar.css, messages.css
│           ├── modals.css, voice.css, inputs.css
│           └── style.css      ← Original (kept for reference)
├── *.html                     ← 18 standalone pages (home, profile, skills, etc.)
├── shared/
│   ├── shell.js               ← Nav bar — inject on every page
│   ├── settings.js            ← Theme/font settings
│   └── theme.css              ← CSS variables and base theme
├── game/
│   ├── index.html             ← Game hub (HTML structure only)
│   ├── js/                    ← Game JS modules
│   │   ├── core.js, reality.js, fantasy.js, celestial.js
│   │   ├── streams.js, browse.js, map.js, info-market.js
│   └── data/                  ← Static JSON data (fetched on demand)
│       ├── solar-system.json, stars-nearby.json, stars-catalog.json
│       ├── constellations.json, cities.json, coastlines.json, milky-way.json
├── desktop/                   ← Tauri v2 desktop app
├── accord/                    ← Humanity Accord (civilizational principles)
├── design/                    ← Architecture and design documentation
└── SELF-HOSTING.md            ← Production server setup guide

The client uses no build step — plain <script src=""> tags load modules in dependency order. All modules share global scope (no ES modules). When in doubt about a function's location, grep the client/ directory.

Adding a New Page

1. Create yourpage.html at the repo root (copy any existing page as template)
2. Add <script src="/shared/shell.js" data-active="yourkey"></script> in <head>
3. Add navTab('/yourpage', 'icon.png', 'Label', 'yourkey') to shared/shell.js
4. Add a mobile drawer entry to shared/shell.js
5. Add nginx route: location = /yourpage { try_files /yourpage.html =404; } on the server
6. Deploy: scp yourpage.html server:/var/www/humanity/

Security

• Server-side Ed25519 signature verification on every message
• E2E encrypted DMs (ECDH P-256 + AES-256-GCM) — server never sees plaintext
• Encrypted user data sync — profile, settings, follows encrypted at rest
• Fibonacci rate limiting + new-account slow mode
• Content Security Policy, HSTS, TLS 1.2+ only
• No IP logging
• Per-session upload tokens with magic-byte validation
• HMAC-SHA256 webhook verification
• Non-root systemd service with hardened sandboxing
• Full audit: SECURITY_AUDIT.md

Transparent AI Development

This project is pioneering fully transparent AI development. Our AI assistant Heron 🪶 (named after Hero of Alexandria) operates with complete openness — public memory files, no black box, every decision documented.

→ See live AI memory · AI workspace rules

Host Your Own Server

Anyone can run a Humanity relay. No permission needed.

git clone https://github.com/Shaostoul/Humanity.git
cd Humanity
cargo build --release -p humanity-relay
./target/release/humanity-relay

Put it behind nginx with TLS (Let's Encrypt is free). People connect with their existing keypair — no migration needed.

→ Full self-hosting guide — nginx config, systemd, federation, admin commands

Want verified federation status? Publicly adopt the Humanity Accord and contact @Shaostoul.

Get Involved

• 💬 Chat first — united-humanity.us/chat — no account needed, just a username
• 💜 Discord — discord.gg/9XxmmeQnWC
• 📦 GitHub — github.com/Shaostoul/Humanity
• 📖 New contributors — start with ONBOARDING.md

Writers, designers, developers, educators, translators — or just someone who cares. Show up and ask what needs doing.

Donate — Every dollar goes toward development and hosting.
→ GitHub Sponsors

Links

🎥 YouTube · 📺 Twitch · 🟢 Rumble · 𝕏 X/Twitter · 📷 Instagram · 🔵 Bluesky · 🟠 Reddit

License

Public domain — CC0 1.0. No permission required. No attribution required. This belongs to humanity.