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. 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 by topic or globally
- 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 .env.example .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

LGPL-2.1-or-later 
## 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