Skip to content

Latest commit

 

History

History
137 lines (110 loc) · 6.31 KB

techstack.md

File metadata and controls

137 lines (110 loc) · 6.31 KB

OpenPleb Technology Stack Guide

This document provides an overview of the technology stack used in the OpenPleb project. It is designed to help new contributors understand the technologies they should focus on learning to effectively contribute to the project.

Overview

OpenPleb is a platform for matching users who want to pay banking QR codes with Bitcoin (makers), and earners who want to earn Bitcoin for paying these offers (takers). The platform facilitates these transactions through a bond system that ensures incentives are aligned for both parties.

The project is structured as a monorepo with multiple packages, each serving a specific purpose in the overall architecture.

Core Architecture

  • Repository Pattern: Monorepo structure with multiple packages in the packages/ directory
  • Languages: TypeScript is used throughout the entire project
  • Database: PostgreSQL with Drizzle ORM for database operations
  • Containerization: Docker and Docker Compose for development and deployment

Backend Technologies

  • Runtime: Bun.js - A fast JavaScript runtime and package manager
  • API Framework: Elysia.js - A fast and type-safe HTTP framework for Bun
  • API Extensions:
    • @elysiajs/cors - CORS support
    • @elysiajs/cookie - Cookie management
    • @elysiajs/jwt - JWT authentication
    • @elysiajs/swagger - API documentation
    • @elysiajs/cron - Scheduled tasks
  • Database ORM: Drizzle ORM - Lightweight TypeScript ORM
  • Bitcoin/Lightning:
    • @cashu/cashu-ts - Cashu protocol implementation for token management
    • @lightningpolar/lnd-api - Lightning Network Daemon API integration
    • light-bolt11-decoder - Lightning invoice decoder
  • Security:
    • @node-rs/argon2 - Password hashing
    • Various cryptographic libraries for security operations
  • Notification Services:
    • @negrel/webpush - Web Push notifications
    • discord.js - Discord bot integration

Frontend Technologies

  • Framework: SvelteKit - A framework for building web applications with Svelte
  • Adapter: @sveltejs/adapter-node - For server-side rendering
  • UI Components:
    • TailwindCSS - Utility-first CSS framework
    • Bits UI - Accessible component primitives
    • Lucide Icons - Consistent icon set
    • svelte-sonner - Toast notifications
    • tailwindcss-animate - Animations
  • State Management:
    • Svelte stores - For persistent and local state management
    • idb - IndexedDB wrapper for client-side storage
  • Special Features:
    • qr-scanner - QR code scanning capability
    • svelte-file-dropzone - File upload functionality
    • @inlang/paraglide-sveltekit - Internationalization
  • Bitcoin/Lightning:
    • @cashu/cashu-ts - Cashu protocol for e-cash tokens
    • @gandlaf21/cashu-wallet-engine - Wallet implementation

Admin Frontend

Similar to the main frontend but with additional administration-specific components:

  • @tanstack/table-core - Advanced table functionality
  • svelte-range-slider-pips - Range slider components

Umbrel App Integration

A separate package for integrating with Umbrel:

  • Simplified SvelteKit application
  • DaisyUI - Component library for Tailwind CSS
  • Tailwind CSS v4

Common Package

Shared code and utilities used across multiple packages:

  • Database schema definitions
  • Type definitions
  • Shared utilities for:
    • Error handling
    • Type conversions
    • LNURL handling

Database Schema

The application uses a relational database with tables for:

  • Offers - Core data structure for payment offers
  • Claims - Records of who claimed which offers
  • Receipts - Payment receipts uploaded by users
  • Proofs - Cryptographic proofs for transactions
  • Tokens - Various tokens used in the bond system
  • Users - User account information
  • Settings - Application settings
  • Fiat Providers - Information about supported fiat payment services

Development Environment

To contribute to OpenPleb, you'll need:

  • Bun.js
  • Docker and Docker Compose
  • PostgreSQL knowledge
  • Node.js/TypeScript experience
  • Understanding of Bitcoin and Lightning Network concepts

Key Concepts to Learn

  1. Svelte/SvelteKit: Understanding component-based architecture and SvelteKit's routing system
  2. Elysia.js: API routing and middleware patterns
  3. Drizzle ORM: Database schema definition and query building
  4. Cashu Protocol: E-cash token concepts and operations
  5. Lightning Network: Understand Lightning network payment flow
  6. TypeScript: Strong typing and interfaces throughout the codebase
  7. TailwindCSS: Utility-first CSS approach
  8. ShadCN: UI component library based on TailwindCSS
  9. Bun.js: Modern JavaScript runtime features

Deployment Architecture

The application is designed to be deployed using Docker containers with the following services:

  • Backend API server
  • Frontend web application
  • Admin frontend
  • PostgreSQL database
  • (Optional) Umbrel app integration

Each component has its own Dockerfile for building containers, and the services are orchestrated using Docker Compose.

Recommended Learning Path for New Contributors

  1. Start with TypeScript fundamentals if not already familiar
  2. Learn Svelte basics and then SvelteKit for routing and layout
  3. Understand TailwindCSS for styling components
  4. Familiarize yourself with Drizzle ORM for database operations
  5. Study Cashu for e-cash tokens
  6. Explore Elysia.js for API development patterns
  7. Get comfortable with Bun.js environment and tooling

With this foundation, you'll be well-equipped to contribute to different aspects of the OpenPleb project.