Reputo is a privacy-preserving, modular reputation-and-voting platform inspired by Snapshot.

  

Table of Contents

1. Apps & Packages
2. Quick Start
3. Prerequisites
4. Project Structure
5. Algorithm Development
6. Contributing
7. License
8. Team

---

Apps & Packages

Path	Stack	Status	Links
apps/api		✅ Ready	📚 README · 📖 API Docs
apps/ui		✅ Ready	📚 README · 🌐 App
apps/workflows	+	✅ Ready	📚 README
apps/typescript-worker	+	✅ Ready	📚 README
packages/reputation-algorithms		✅ Ready	📚 README
packages/algorithm-validator		✅ Ready	📚 README
packages/database	+	✅ Ready	📚 README
packages/storage		✅ Ready	📚 README

---

Quick Start

Local development (pnpm)

# Install dependencies
pnpm install

# Build project
pnpm build

# Run all services in parallel
pnpm dev

# Run individual services
pnpm -F @reputo/api dev   # API only

Local development (Docker Compose)

Minimal local stack

# Basic local development setup
docker compose -f docker/docker-compose.dev.yml up --build

---

Prerequisites

Development Environment

• Node.js: 20.x or higher
• pnpm: 10.12.4 or higher
• Docker: For containerized development
• Git: With Lefthook for git hooks

Production/Staging Deployment

• Docker & Docker Compose: Container orchestration
• Traefik: Reverse proxy
• Domain & DNS: For SSL certificate generation
• Cloudflare API Token: For DNS challenge

---

Project Structure

reputo/
├── apps/
│   ├── api/                        # NestJS API server
│   ├── ui/                         # Next.js frontend
│   ├── workflows/                  # Temporal workflows
│   └── typescript-worker/          # Algorithm execution worker
├── packages/
│   ├── algorithm-validator/        # Shared Zod validation library
│   ├── reputation-algorithms/      # Algorithm definitions registry
│   ├── storage/                    # Framework-agnostic S3 utilities
│   └── database/                   # Mongoose database layer
├── scripts/
│   ├── create-algorithm.ts         # Unified algorithm creation CLI
│   └── validate-algorithms.ts      # Algorithm sync validation CLI
├── docker/
│   ├── docker-compose.yml          # Production/staging setup
│   ├── docker-compose.dev.yml      # Local development
│   ├── docker-compose.preview.yml  # PR preview environments
│   ├── Dockerfile                  # Multi-stage build
│   └── traefik.yml                 # Reverse proxy config
├── .github/
│   ├── workflows/                  # CI/CD pipelines
│   └── PULL_REQUEST_TEMPLATE.md
├── coverage/                       # Test coverage reports
├── node_modules/                   # pnpm workspace dependencies
├── package.json                    # Root workspace config
├── pnpm-workspace.yaml             # Workspace definition
├── biome.json                      # Linting & formatting
├── lefthook.yml                    # Git hooks
├── vitest.config.ts                # Test runner config
├── tsconfig.vitest.json            # Vitest TS config
└── commitlint.config.mjs           # Commit message linting

Environments

We follow a three-tier deployment strategy with automated promotion:

Preview Environment (Pull Requests)

• Trigger: Adding pullpreview label to PRs
• Infrastructure: AWS Lightsail
• URL: Dynamic subdomain generated per PR
• Cleanup: Auto-expires after 48h or PR closure

Staging Environment

• Trigger: Merge to main branch (automated)
• URL:
  • UI: staging.logid.xyz
  • API: api-staging.logid.xyz
  • Traefik: traefik-staging.logid.xyz/dashboard
• Deployment: Watchtower auto-pulls staging tagged images

Production Environment

• Trigger: Manual workflow dispatch with commit SHA
• URL:
  • UI: logid.xyz
  • API: api.logid.xyz
  • Traefik: traefik.logid.xyz/dashboard
• Process: Promotes staging images with production tags

---

Algorithm Development

This section guides you through creating, configuring, and implementing reputation algorithms.

Overview

Algorithms in Reputo consist of two parts:

1. Algorithm Definition - A JSON schema that describes the algorithm's metadata, inputs, outputs, and runtime configuration. Located in packages/reputation-algorithms/src/registry/.

2. Activity Implementation - TypeScript code that executes the algorithm logic. Located in apps/typescript-worker/src/activities/.

Step 1: Create a New Algorithm

Use the unified CLI to create both the definition and activity scaffold in one command:

pnpm algorithm:create <key> <version>

Example:

pnpm algorithm:create proposal_engagement 1.0.0

This creates:

• packages/reputation-algorithms/src/registry/proposal_engagement/1.0.0.json - Algorithm definition
• apps/typescript-worker/src/activities/proposal_engagement.activity.ts - Activity scaffold

Requirements:

• key must be snake_case (e.g., voting_engagement, proposal_score)
• version must be valid SemVer (e.g., 1.0.0, 2.1.0-beta)

Step 2: Configure the Algorithm Definition

Edit the generated JSON file to define your algorithm's schema:

{
    "key": "proposal_engagement",
    "name": "Proposal Engagement",
    "category": "Engagement",
    "description": "Calculates user engagement based on proposal interactions",
    "version": "1.0.0",
    "inputs": [
        {
            "key": "proposals",
            "label": "Proposals CSV",
            "type": "csv",
            "csv": {
                "hasHeader": true,
                "columns": [
                    { "key": "user_id", "type": "string" },
                    { "key": "proposal_id", "type": "string" },
                    {
                        "key": "action",
                        "type": "enum",
                        "enum": ["view", "vote", "comment"]
                    }
                ]
            }
        }
    ],
    "outputs": [
        {
            "key": "engagement_scores",
            "label": "Engagement Scores",
            "type": "csv",
            "csv": {
                "columns": [
                    { "key": "user_id", "type": "string" },
                    { "key": "score", "type": "number" }
                ]
            }
        }
    ],
    "runtime": {
        "taskQueue": "typescript-worker",
        "activity": "proposal_engagement"
    }
}

Key fields:

Field	Description
inputs	Define expected input data schema (CSV columns, types, constraints)
outputs	Define output data schema
runtime.activity	Must match the exported function name in the activity file

Step 3: Implement the Activity Logic

Edit the generated activity file to implement your algorithm:

// apps/typescript-worker/src/activities/proposal_engagement.activity.ts

export async function proposal_engagement(
    payload: WorkerAlgorithmPayload
): Promise<WorkerAlgorithmResult> {
    const { snapshotId, algorithmKey, inputLocations } = payload

    // 1. Get input data
    const inputKey = getInputLocation(inputLocations, 'proposals')
    const buffer = await storage.getObject(inputKey)
    const rows = parse(buffer.toString('utf8'), { columns: true })

    // 2. Implement your algorithm logic
    const scores = computeEngagementScores(rows)

    // 3. Serialize and upload output
    const outputCsv = stringify(scores, { header: true })
    const outputKey = generateSnapshotOutputKey(snapshotId, algorithmKey)
    await storage.putObject(outputKey, outputCsv, 'text/csv')

    // 4. Return output locations
    return {
        outputs: {
            engagement_scores: outputKey,
        },
    }
}

Step 4: Validate Synchronization

Ensure all algorithm definitions have corresponding activity implementations:

pnpm algorithm:validate

This checks:

• Every definition has a matching activity file
• Every definition has a matching activity export
• Every activity file is exported in the index

Step 5: Build and Test

# Validate and build the algorithms package
pnpm --filter @reputo/reputation-algorithms build

# Build the worker
pnpm --filter @reputo/typescript-worker build

# Run tests
pnpm test

Adding a New Version

To add a new version of an existing algorithm:

pnpm algorithm:create voting_engagement 2.0.0

This creates a new version file. The activity implementation is shared across versions unless you need version-specific logic.

CLI Reference

Command	Description
pnpm algorithm:create <key> <version>	Create algorithm definition + activity scaffold
pnpm algorithm:validate	Validate definitions and activities are in sync
pnpm --filter @reputo/reputation-algorithms algorithm:create <key> <version>	Create definition only
pnpm --filter @reputo/typescript-worker algorithm:new <key>	Create activity only

---

Contributing

Branching Strategy: GitHub Flow

1. Create feature branch from main

   git checkout -b feature/your-feature-name

2. Open Pull Request to main

   • Add pullpreview label for preview deployment
   • Ensure CI passes
   • Request review from maintainers

3. Merge after approval

---

License

Released under the GPL-3.0 license. See LICENSE file for details.

---

Team

Cyrille Derche	Mohammad Khaki	Behzad Rabiei