LatterFix

Decentralized Payroll & Task Management Platform

Powered by Stellar Soroban Smart Contracts

Live Demo · PRD (Markdown) · Download PRD (PDF) · Report Bug

📋 Table of Contents

Overview
✨ Key Features
🏗️ Architecture
🚀 Quick Start
📸 Screenshots
🔧 Technology Stack
📖 Documentation
🤝 Contributing
📄 License

Overview

LatterFix is a fully on-chain decentralized task management and escrow platform built on Stellar Soroban smart contracts. It allows task creators to fund work via smart contract escrow, and contributors to earn instant USDC/XLM/EURC payouts the moment their delivery is verified — entirely without a centralized backend.

Every user action (task creation, assignment, work submission, dispute, governance vote) constructs a real Soroban transaction using @stellar/stellar-sdk, simulates it against the Soroban RPC, routes the XDR to the user's wallet for signing (Freighter, xBull, Lobstr), and polls for ledger confirmation before updating the UI.

The Problem We Solve

Challenge	Traditional Systems	LatterFix Solution
Payment Trust	40% of freelancers face payment disputes	Smart contract escrow ensures guaranteed payments
Transaction Fees	5-15% for international transfers	~$0.000005 per transaction on Stellar
Settlement Time	3-5 business days	3-5 seconds finality
Global Access	Requires bank account	Only needs internet & wallet
Reputation Tracking	Platform-locked, opaque	On-chain, portable reputation

Why Stellar?

┌─────────────────────────────────────────────────────────────────┐
│                     Why We Built on Stellar                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ⚡ LIGHTNING FAST          💰 NEAR-ZERO FEES                  │
│   3-5 second settlement      $0.000005 per transaction          │
│                                                                  │
│   🌍 GLOBAL ACCESS           🔐 TRUSTLESS ESCROW                │
│   50+ currencies via anchors Smart contract locked funds        │
│                                                                  │
│   📜 IMMUTABLE RECORDS       🏦 NO BANK REQUIRED                │
│   All transactions on ledger  Financial inclusion for all       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

✨ Key Features

⛓️ Real Soroban Contract Integration

Full transaction lifecycle — Simulate → Prepare → Sign → Submit → Poll for every action
20+ contract methods exposed via sorobanTaskContract.ts service
Wallet support — Freighter, xBull, Lobstr via @creit.tech/stellar-wallets-kit
Simulation-first — Every tx is simulated against Soroban RPC before wallet prompt

🔒 On-Chain Escrow

create_task() locks reward tokens in Soroban contract storage
complete_task() releases net payout (reward minus 2.5% platform fee) to contributor
dispute_task() freezes escrow awaiting admin resolve_dispute() with custom split
cancel_task() refunds creator in full

📊 Live Horizon & RPC Data

Real account balances — XLM, USDC, EURC queried from Horizon on every page
Network congestion — Live fee stats from /fee_stats endpoint in AppNav
Transaction history — Paginated Horizon tx list, claimable balances, Soroban getEvents
Live ledger number — Shown on landing page, updates on mount

🗳️ On-Chain Governance

create_proposal() / cast_vote() / execute_proposal() all wallet-signed
grant_role() / pause_all() / unpause_all() for admin circuit-breaking
Live proposals fetched from Soroban RPC on page load

👤 On-Chain Profiles & Reputation

Tiered reputation system — Newcomer → Contributor → Expert → Master → Legend
get_profile() / get_user_reputation() / get_user_tier() called from Profile page
slash_reputation() / reward_contribution() for admin reputation management
total_earnings tracked cumulatively in on-chain profile storage

🛡️ Access Control & Pausable

Role-based auth — Admin / Moderator / Verifier with require_auth() guards
Granular pause — Each of 7 actions can be independently paused/unpaused
Emergency circuit-breaker — pause_all() halts the entire contract in one call

🏗️ Architecture

LatterFix is a backend-free dApp — all state lives on the Stellar ledger.

┌──────────────────────────────────────────────────────────────────┐
│                      LATTERFIX ARCHITECTURE                       │
├──────────────────────────────────────────────────────────────────┤
│                                                                    │
│  React 19 + TypeScript (Vite)                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐  │
│  │Dashboard │ │Explorer  │ │Escrow Mgr│ │Governance│ │Profile │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘  │
│       │             │            │             │            │       │
│  ┌────▼─────────────▼────────────▼─────────────▼────────────▼────┐ │
│  │         useContractTask / useHorizonAccount hooks              │ │
│  │         sorobanTaskContract.ts service layer                   │ │
│  └─────────────────────────────┬──────────────────────────────────┘ │
│                                 │                                    │
│  ┌──────────────────────────────▼──────────────────────────────┐   │
│  │           Stellar Wallets Kit (Freighter / xBull / Lobstr)   │   │
│  │         simulate → prepare XDR → sign → submit → poll       │   │
│  └──────────────────────────────┬──────────────────────────────┘   │
│                                 │                                    │
└─────────────────────────────────┼────────────────────────────────────┘
                                  │
               ┌──────────────────┴──────────────────┐
               │                                     │
   ┌───────────▼───────────┐           ┌─────────────▼────────────┐
   │   Soroban RPC          │           │   Stellar Horizon API     │
   │  simulateTransaction   │           │  account balances        │
   │  sendTransaction       │           │  tx history              │
   │  getEvents (contract)  │           │  fee_stats (live)        │
   │  getTransaction        │           │  claimable balances      │
   └───────────┬────────────┘           └─────────────┬────────────┘
               │                                       │
               └──────────────────┬────────────────────┘
                                  │
                    ┌─────────────▼──────────────┐
                    │  Stellar Testnet Ledger      │
                    │  LatterFix TaskManager       │
                    │  Soroban Contract (Rust/Wasm) │
                    └──────────────────────────────┘

Data Flow: Payroll Payment

┌─────────────────────────────────────────────────────────────────────────┐
│                     PAYROLL PAYMENT FLOW                                 │
└─────────────────────────────────────────────────────────────────────────┘

  Organization Admin          LatterFix Platform            Stellar Network
        │                           │                              │
        │  1. Create Payroll Batch  │                              │
        │──────────────────────────▶│                              │
        │                           │                              │
        │  2. Fund Batch (USDC)     │                              │
        │──────────────────────────▶│                              │
        │                           │  3. Lock in Escrow           │
        │                           │─────────────────────────────▶│
        │                           │                              │
        │                           │  ⏳ Awaiting Completion      │
        │                           │                              │
        │  4. Approve Payments      │                              │
        │──────────────────────────▶│                              │
        │                           │  5. Execute Bulk Payment     │
        │                           │─────────────────────────────▶│
        │                           │                              │
        │                           │  ⚡ 3-5 second settlement    │
        │                           │◀─────────────────────────────│
        │                           │                              │
        │  6. Confirmation          │                              │
        │◀──────────────────────────│                              │
        │                           │                              │
        │                    Employees Receive                      │
        │                    Instant Payment 💰                      │

🚀 Quick Start

Prerequisites

Node.js 18+
PostgreSQL 14+
Redis 6+
Stellar Wallet (Freighter recommended)

Installation

# Clone the repository
git clone https://github.com/LatterFix/LatterFix-frontend.git
cd LatterFix-frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
cd backend
npm run db:migrate

# Start development servers
npm run dev

Environment Configuration

# Backend (.env)
DATABASE_URL=postgresql://user:password@localhost:5432/latterfix
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-jwt-secret
STELLAR_NETWORK=testnet

# Frontend (.env)
VITE_API_URL=http://localhost:3001
VITE_STELLAR_NETWORK=testnet

Development Servers

Service	Port	Description
Frontend	5173	React + Vite dev server
Backend	3001	Express API server
Redis	6379	Cache & job queues

📸 Application Showcase

Brand Identity & Design System

Interactive Landing & Contract Explorer

Our root layout showcases an interactive contract browser designed to let developers explore, query, and test Soroban functions directly from their browser:

Enterprise Workspace & Operations

The workspace dashboard integrates employee rosters, smart escrow trackers, and historical transaction ledgers into a single, cohesive pane:

🎨 Visual Architecture

System Architecture Diagram

graph TD
    User([User Client]) -->|Web3 Wallet| WalletKit[Stellar Wallets Kit]
    User -->|React Router| FE[React 19 Frontend]
    FE -->|Zustand Store| Store[Zustand Local State]
    FE -->|HTTPS / WSS| BE[Node.js Express Backend]
    BE -->|Query / Mutate| DB[(PostgreSQL Database)]
    BE -->|Job Queues| Queue[BullMQ + Redis]
    WalletKit -->|Sign Tx| Stellar[Stellar Network Ledger]
    FE -->|Query State| Stellar

Payment Escrow Flow Diagram

sequenceDiagram
    autonumber
    actor Admin as Organization Admin
    participant Platform as LatterFix Platform
    participant Stellar as Stellar Ledger
    actor Contributor as Assigned Contributor

    Admin->>Platform: Create Task & Set Reward
    Admin->>Platform: Fund Escrow (XLM/USDC)
    Platform->>Stellar: Lock Tokens in Soroban Escrow Contract
    Contributor->>Platform: Apply & Accept Assignment
    Contributor->>Platform: Complete Work & Submit Delivery URL
    Admin->>Platform: Verify Deliverable
    Platform->>Stellar: Trigger verify() release
    Stellar->>Platform: Deduct Platform Fee (2.5%)
    Stellar->>Contributor: Disburse Net Payout

Multi-Tenant Isolation Flow

graph LR
    TenantA[Tenant A Session] -->|JWT Claims| RLS[PostgreSQL Row-Level Security]
    TenantB[Tenant B Session] -->|JWT Claims| RLS
    RLS -->|Scope Isolation| Table[(Organization Ledger Table)]
    Table -->|Only Tenant A Data| TenantA
    Table -->|Only Tenant B Data| TenantB

🔧 Technology Stack

Frontend

Technology	Version	Purpose
React	19	UI framework
TypeScript	5.9	Type safety
Vite	7	Build tool
Zustand	latest	Client state management
@stellar/stellar-sdk	latest	Transaction building, XDR, Horizon
@creit.tech/stellar-wallets-kit	latest	Freighter / xBull / Lobstr
Vanilla CSS	—	Styling (no Tailwind)
lucide-react	latest	Icons

Stellar Integration Layer

Module	What it does
`sorobanTaskContract.ts`	20+ contract methods, simulate → sign → poll
`stellar.ts`	Horizon account ops, path payments, claimable balances, trustlines
`transactionHistory.ts`	Paginated Horizon txs, `getEvents` RPC, fee stats
`useContractTask.ts`	React hook wiring contract actions to wallet
`useHorizonAccount.ts`	Live XLM/USDC/EURC balances from Horizon

Smart Contract (Rust / Soroban)

Module	Responsibility
`lib.rs`	Public contract entrypoint (20+ methods)
`escrow.rs`	Task state machine & token locking
`governance.rs`	Proposals, voting, execution
`reputation.rs`	Tiered points system & leaderboard
`access_control.rs`	Role-based auth with `require_auth()`
`pausable.rs`	Granular + global circuit-breaker
`user_profile.rs`	On-chain profiles, earnings, avatar
`storage.rs`	TTL management, statistics, categories
`events.rs`	22 timestamped event emitters

📖 Documentation

Document	Description
Architecture Diagram	System architecture details
Multi-Tenant Setup	Tenant configuration guide
API Documentation	REST API reference
Testing Guide	Test instructions
SDS Integration	Stellar Data Service docs

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Quality

# Run linter
npm run lint

# Format code
npm run format

# Run tests
npm test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ on Stellar

Website · Documentation · Discord · Twitter

Name		Name	Last commit message	Last commit date
Latest commit History 392 Commits
.github		.github
.husky		.husky
.vite/deps		.vite/deps
.vscode		.vscode
backend		backend
contracts		contracts
docs		docs
public		public
src		src
src_backup		src_backup
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc		.prettierrc
ARCHITECTURE_DIAGRAM.md		ARCHITECTURE_DIAGRAM.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRACT_REGISTRY_IMPLEMENTATION.md		CONTRACT_REGISTRY_IMPLEMENTATION.md
CONTRACT_REGISTRY_STATUS.md		CONTRACT_REGISTRY_STATUS.md
CONTRIBUTING.md		CONTRIBUTING.md
CRITICAL_FIX_NOTES.md		CRITICAL_FIX_NOTES.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
IMPLEMENTATION_CHECKLIST.md		IMPLEMENTATION_CHECKLIST.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
ISSUES.md		ISSUES.md
LICENSE		LICENSE
MULTI_TENANT_IMPLEMENTATION.md		MULTI_TENANT_IMPLEMENTATION.md
PR_DESCRIPTION.md		PR_DESCRIPTION.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SECURITY.md		SECURITY.md
VERIFICATION_GUIDE.md		VERIFICATION_GUIDE.md
demo-contract-registry.md		demo-contract-registry.md
environments.toml		environments.toml
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
rust-toolchain.toml		rust-toolchain.toml
test-contract-endpoint.sh		test-contract-endpoint.sh
test-contract-registry.sh		test-contract-registry.sh
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
upstream_EmployeeEntry.tsx		upstream_EmployeeEntry.tsx
upstream_PayrollScheduler.tsx		upstream_PayrollScheduler.tsx
vite.config.ts		vite.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation