likwid/README.md

# Likwid - Modular Governance Platform

## Composable Governance Infrastructure

A modular toolkit for deliberation, voting, delegation, moderation, and plugins — configure what you need per community.

Likwid is an open-source platform for participatory governance. Assemble decision-making workflows from modular building blocks: deliberation, voting methods, delegation, moderation, and plugins.

> *"We are citizens of the 21st century, but we rely on institutions designed in the 19th century, through means designed in the 13th century. The problem is not democracy, it's the interface."*

## Philosophy

Likwid implements a set of principles for **modular governance infrastructure**:

- **Information must be understandable**, not just available
- **Listening matters more than speaking** — structured deliberation over flame wars
- **Voting should express nuance** — from simple approval to Schulze and quadratic methods
- **Delegation should be fluid** — trust networks that adapt in real-time
- **Governance should be composable** — workflows assembled from modules, not imposed

## Features

### Deliberative Democracy
- **Inform → Discuss → Decide** workflow for proposals
- Resource libraries for informed participation
- Small group discussions with facilitators
- "Read before discuss" requirements
- Constructive comment visibility scoring

### Advanced Voting Methods
- **Approval Voting** — vote for multiple options
- **Ranked Choice** — order preferences
- **Schulze Method** — Condorcet-consistent pairwise comparison
- **STAR Voting** — score + automatic runoff
- **Quadratic Voting** — express intensity of preference

### Liquid Delegation
- Delegate your vote globally or within a community
- Real-time transparency: see how delegates vote
- Revoke delegation instantly
- Transitive delegation chains
- Delegation analytics and trust networks

### Modular Plugin System
- WASM-based sandboxed plugins
- Per-community plugin configuration
- Hook-based architecture (actions/filters)
- Built-in and third-party plugins
- Admin policy for signed/unsigned plugins

### Governance Infrastructure
- Multi-community platform support
- Granular admin controls (platform mode, registration, moderation)
- Public moderation ledger (immutable)
- Role-based access (admin, moderator, facilitator, member)
- Anonymous voting with identity separation

## Tech Stack

| Layer | Technology |
|-------|------------|
| **Backend** | Rust (Axum 0.8, Tokio, SQLx) |
| **Frontend** | Astro + TypeScript |
| **Database** | PostgreSQL 16 |
| **Plugins** | WebAssembly (wasmtime) |
| **Containers** | Podman (rootless) |

## Quick Start

### Prerequisites

**Windows:**
- Windows 10/11 with WSL2
- Podman Desktop (WSL2 backend)
- Rust (rustup, MSVC toolchain)
- Node.js LTS

**Linux:**
- Podman + podman-compose
- Rust (rustup)
- Node.js LTS

### Development

```powershell
# 1. Clone and configure
git clone https://invent.kde.org/marcoa/likwid.git
cd likwid
cp backend/.env.example backend/.env

# 2. Start everything (database + backend + frontend)
.\scripts\dev-start.ps1

# 3. Stop everything
.\scripts\dev-stop.ps1
```

The platform will be available at:
- **Frontend**: http://localhost:4321
- **Backend API**: http://localhost:3000
- **Setup Wizard**: http://localhost:4321/setup (first run)

### First Run

1. Navigate to `/register` to create the first user (automatically becomes admin)
2. Complete platform setup at `/setup`
3. Configure instance settings at `/admin/settings`
4. Create your first community

## Project Structure

```
likwid/
├── backend/              # Rust backend
│   ├── src/
│   │   ├── api/          # REST endpoints
│   │   ├── auth/         # JWT authentication
│   │   ├── models/       # Database models
│   │   └── plugins/      # Plugin system (WASM + builtins)
│   └── migrations/       # SQL migrations
├── frontend/             # Astro frontend
│   ├── src/
│   │   ├── pages/        # Routes
│   │   ├── layouts/      # Page layouts
│   │   └── components/   # UI components
├── compose/              # Podman compose files
├── scripts/              # Dev scripts (cross-platform)
└── docu_dev/             # Design documents
```

### Core Principles

1. **Be considerate** — Your work affects others
2. **Be respectful** — Assume good intentions
3. **Be collaborative** — Work transparently
4. **Be pragmatic** — Results over debates
5. **Find a third way** — Seek solutions that satisfy everyone

## License

EUPL-1.2
## Acknowledgments

Inspired by:
- [Pol.is](https://pol.is/) — Opinion mapping
- [Decidim](https://decidim.org/) — Participatory democracy
- [LiquidFeedback](https://liquidfeedback.org/) — Liquid democracy
- [Equal Vote Coalition](https://www.equal.vote/) — STAR Voting