likwid/README.md

# Likwid - Modular Governance Platform

**Democracy Design in Practice**

Likwid is an open-source platform for participatory governance, designed to make collective decision-making accessible, transparent, and genuinely democratic. Built for communities, civic organizations, and any group that values structured deliberation over shouting matches.

> *"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 the principles of **Democracy Design**:

- **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
- **Participation is designed**, 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

## Roadmap

- [x] Core voting infrastructure
- [x] Plugin system (WASM + builtins)
- [x] Deliberation phases
- [x] Comment quality scoring
- [ ] Advanced voting methods (Schulze, STAR, Quadratic)
- [ ] Liquid delegation engine
- [ ] GitLab/GitHub integration - plugin
- [ ] Mobile-responsive UI
- [ ] Accessibility audit (WCAG 2.1)

## 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