# rVote — Decision Engine

**Module ID:** `rvote`
**Domain:** `rvote.online`
**Version:** 0.1.0
**Framework:** Next.js 16 / React 19 / Prisma / PostgreSQL
**Status:** Active

## Purpose

Credit-weighted conviction voting engine for collaborative governance. Spaces can run ranked proposals with configurable parameters — daily credit allocation, promotion thresholds, voting periods — and binary final votes. Integrates with the r*.online ecosystem via EncryptID passkey authentication.

## Data Model

### Core Entities (Prisma)

| Model | Key Fields | Relationships |
|-------|-----------|---------------|
| **User** | id, did (EncryptID DID), username, totalCredits | has many SpaceMember, Proposal, Vote, FinalVote |
| **Space** | slug, name, visibility, promotionsThreshold, votingPeriodHours, dailyCredits, maxCredits, startingCredits | has many SpaceMember, SpaceInvite |
| **SpaceMember** | userId, spaceSlug, role (ADMIN/MEMBER), credits, lastCreditUpdate | belongs to User, Space |
| **SpaceInvite** | spaceSlug, email, token, role, expiresAt, maxUses, useCount | belongs to Space |
| **Proposal** | id, title, description, spaceSlug, authorId, status, voteCount, finalYes/No/Abstain | belongs to Space, User; has many Vote, FinalVote |
| **Vote** | userId, proposalId, weight, credits, decayTime | ranking phase vote |
| **FinalVote** | userId, proposalId, vote (YES/NO/ABSTAIN) | binary phase vote |

### Proposal Status Flow

```
RANKING → (crosses threshold) → VOTING → (period expires) → PASSED / FAILED
                                                           → ARCHIVED (manual)
```

## Permission Model

### Space Integration

- **SpaceVisibility:** All four levels supported (public, public_read, authenticated, members_only)
- **Default role for open spaces:** PARTICIPANT (can view proposals and vote)

### Capabilities

| Capability | Required SpaceRole | AuthLevel | Description |
|-----------|-------------------|-----------|-------------|
| `view_proposals` | VIEWER | BASIC | See proposal list and details |
| `create_proposal` | PARTICIPANT | STANDARD | Submit new proposals |
| `cast_vote` | PARTICIPANT | STANDARD | Vote on ranking and final phases |
| `moderate_proposals` | MODERATOR | STANDARD | Edit/archive others' proposals |
| `configure_voting` | ADMIN | ELEVATED | Change space voting parameters |

### Module-Specific Overrides

Currently uses `SpaceRole { ADMIN, MEMBER }` in Prisma. Migration path:
- `MEMBER` → `PARTICIPANT`
- Add `VIEWER` and `MODERATOR` to the Prisma enum
- Replace `requireSpaceMembership()` / `requireSpaceAdmin()` with `hasCapability()` from SDK

### Current Auth Implementation

- NextAuth 5 (beta) + EncryptID session
- `requireSpaceMembership(slug, session)` checks SpaceMember table
- `requireSpaceAdmin(slug, session)` checks SpaceMember.role === ADMIN

## API Endpoints

| Method | Path | Auth Required | Capability | Description |
|--------|------|---------------|------------|-------------|
| GET | /api/spaces | No | — | List public spaces |
| POST | /api/spaces | Yes | — | Create a new space |
| GET | /api/spaces/[slug] | Depends | view_proposals | Get space info |
| PUT | /api/spaces/[slug] | Yes | configure_voting | Update space settings |
| GET | /api/spaces/[slug]/members | Yes | view_proposals | List space members |
| POST | /api/spaces/[slug]/members | Yes | configure_voting | Add member |
| GET | /api/proposals | Depends | view_proposals | List proposals in space |
| POST | /api/proposals | Yes | create_proposal | Create proposal |
| POST | /api/proposals/[id]/vote | Yes | cast_vote | Submit ranking vote |
| POST | /api/proposals/[id]/final-vote | Yes | cast_vote | Submit final vote |
| GET/POST | /api/spaces/[slug]/invites | Yes | configure_voting | Manage invites |

## Canvas Integration

rVote can embed as a `demo-poll` shape in the rSpace canvas:
- Shape type: `demo-poll`
- Displays question + vote counts inline on canvas
- Click to expand into full voting interface
- Real-time vote count sync via Automerge

## Cross-Module Dependencies

| Module | Integration |
|--------|------------|
| **rSpace** | Embedded poll shapes on canvas |
| **rFunds** | Proposals can trigger funding flows when passed |
| **rNetwork** | Voter graph visualization |
| **canvas-website** | Tldraw integration via shape system |

## Local-First / Offline Support

- Currently server-authoritative (Prisma/PostgreSQL)
- No offline vote caching
- Future: CRDT proposal state for offline draft proposals, sync on reconnect

## Migration Plan

1. Add `VIEWER` and `MODERATOR` to Prisma `SpaceRole` enum (migration)
2. Rename existing `MEMBER` data to `PARTICIPANT` (data migration)
3. Import `SpaceRole` from `@encryptid/sdk` types for client-side use
4. Replace `requireSpaceMembership()` with `hasCapability(role, cap, RVOTE_PERMISSIONS)`
5. Replace `requireSpaceAdmin()` with `hasCapability(role, 'configure_voting', RVOTE_PERMISSIONS)`
6. Add `resolveSpaceRole()` call in API route middleware