Skip to content

web

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

web

README.md

KindFi Web Application

A Next.js 16 web application for blockchain-powered social impact crowdfunding, built on Stellar/Soroban with WebAuthn passkey authentication.

🚀 Features

  • 🔐 Passkey Authentication: WebAuthn-based passwordless authentication with smart account integration
  • 🌐 Stellar Blockchain Integration: Smart contracts, escrow, and token transfers via Stellar/Soroban
  • 💼 Smart Wallets: OpenZeppelin Smart Account Kit integration for secure wallet management
  • 📊 Project Management: Create, manage, and support social impact projects with milestone-based funding
  • 🔒 Escrow System: Trustless Work escrow integration for secure, milestone-based fund releases
  • 👤 KYC Verification: Identity verification powered by Didit - AI-native KYC with support for 220+ countries, liveness detection, and document verification
  • 💬 Community Features: Comments, Q&A, project updates, and supporter tracking
  • 🔔 Notifications: Push notifications and real-time updates
  • 📰 Content Management: MDX-based news/blog system with RSS feeds
  • 🌍 Internationalization: Multi-language support (i18n)
  • 📱 Responsive Design: Mobile-first design with Tailwind CSS and Shadcn UI

🛠️ Tech Stack

Core

  • Next.js 16 - React framework with App Router
  • React 19 - UI library
  • TypeScript - Type safety
  • Bun - Package manager and runtime

Authentication & Security

  • NextAuth.js - Authentication framework
  • @simplewebauthn - WebAuthn/Passkey implementation
  • smart-account-kit - Stellar smart account management
  • Supabase - Database and authentication backend
  • Didit - AI-native identity verification and KYC platform

Blockchain

  • @stellar/stellar-sdk - Stellar blockchain SDK
  • @openzeppelin/relayer-sdk - Transaction relaying
  • @trustless-work/escrow - Escrow contract integration
  • @creit-tech/stellar-wallets-kit - Wallet connectivity

UI & Styling

  • Tailwind CSS - Utility-first CSS framework
  • Shadcn UI - Component library (Radix UI primitives)
  • Framer Motion - Animation library
  • TipTap - Rich text editor
  • Lucide React - Icon library

Data & State Management

  • @tanstack/react-query - Server state management
  • Drizzle ORM - Type-safe database queries
  • React Hook Form - Form management
  • Zod - Schema validation

Additional Tools

  • MDX - Markdown with JSX
  • Redis/Upstash - Rate limiting and caching
  • Resend - Email service
  • Biome - Linting and formatting

📁 Project Structure

apps/web/
├── app/                          # Next.js App Router
│   ├── (auth-pages)/            # Authentication routes
│   │   ├── sign-in/
│   │   ├── sign-up/
│   │   ├── passkey-registration/
│   │   └── reset-password/
│   ├── (routes)/                # Public routes
│   │   ├── home/
│   │   ├── projects/
│   │   │   └── [slug]/
│   │   │       └── manage/     # Project management
│   │   ├── profile/
│   │   ├── about/
│   │   └── create-project/
│   ├── api/                     # API routes
│   │   ├── auth/               # NextAuth endpoints
│   │   ├── passkey/           # WebAuthn endpoints
│   │   ├── stellar/           # Stellar blockchain APIs
│   │   ├── escrow/            # Escrow operations
│   │   ├── projects/          # Project CRUD
│   │   ├── comments/          # Comments system
│   │   └── notifications/      # Push notifications
│   ├── actions/               # Server actions
│   ├── news/                  # MDX blog/news
│   └── layout.tsx
├── components/
│   ├── base/                  # Shadcn UI components
│   ├── shared/               # Shared components
│   │   ├── layout/           # Header, Footer, Layout
│   │   ├── kyc/              # KYC flow components
│   │   └── qa/               # Q&A components
│   ├── sections/             # Page sections
│   ├── pages/                # Page-level components
│   └── cards/                # Card components
├── hooks/
│   ├── contexts/             # React contexts
│   ├── passkey/              # Passkey hooks
│   ├── stellar/              # Stellar hooks
│   ├── escrow/               # Escrow hooks
│   └── projects/            # Project hooks
├── lib/
│   ├── auth/                  # Auth utilities
│   ├── stellar/              # Stellar utilities
│   ├── queries/               # React Query queries
│   ├── services/              # Service layer
│   ├── types/                 # TypeScript types
│   ├── utils/                 # Utility functions
│   ├── validators/            # Zod schemas
│   ├── constants/            # App constants
│   ├── i18n/                  # Internationalization
│   └── email/                 # Email templates
├── auth/                      # Custom auth adapters
├── content/                   # MDX content files
├── public/                    # Static assets
├── middleware.ts              # Next.js middleware
├── next.config.ts             # Next.js configuration
├── tailwind.config.ts         # Tailwind configuration
└── tsconfig.json              # TypeScript configuration

🚀 Getting Started

Prerequisites

  • Bun >= 1.3.14
  • Node.js >= 20
  • Supabase account (for database)
  • Stellar testnet/mainnet access
  • Didit account (for KYC verification) - Sign up for free

Installation

  1. Install dependencies (from monorepo root):
bun run init

Or from this directory:

bun install
  1. Set up environment variables:

Create a .env file in apps/web/ with the following variables:

# Database
DATABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_nextauth_secret

# Stellar
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"

# Smart Account Kit
NEXT_PUBLIC_ACCOUNT_WASM_HASH=your_account_wasm_hash
NEXT_PUBLIC_WEBAUTHN_VERIFIER_ADDRESS=your_verifier_address

# Escrow (Trustless Work)
NEXT_PUBLIC_ESCROW_CONTRACT_ADDRESS=your_escrow_contract
TRUSTLESS_WORK_API_KEY=your_api_key

# Redis (for rate limiting)
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token

# Email (Resend)
RESEND_API_KEY=your_resend_key

# KYC (Didit)
DIDIT_API_KEY=your_didit_api_key
DIDIT_WEBHOOK_SECRET=your_didit_webhook_secret

# KYC enforcement (server-only; keep disabled in production)
# Requires a redeploy / process restart to take effect.
KYC_ENFORCEMENT_MODE=disabled
KYC_ENFORCED_ACTIONS=send_assets,use_off_ramp

# Other
NEXT_PUBLIC_APP_URL=http://localhost:3000

💡 Note: Check with the KindFi team for development credentials or use the .env.sample template.

  1. Run the development server:

From monorepo root:

task web:dev

Or from this directory:

bun dev
  1. Open your browser:

Navigate to http://localhost:3000

🏗️ Architecture

Authentication Flow

  1. Traditional Auth: Email/password with NextAuth + Supabase
  2. Passkey Auth: WebAuthn registration → Smart Account creation → Stellar wallet
  3. Session Management: NextAuth sessions with Supabase token refresh

Blockchain Integration

  • Smart Accounts: OpenZeppelin Smart Account Kit for passkey-secured wallets
  • Transactions: Stellar SDK for building and signing transactions
  • Escrow: Trustless Work for milestone-based fund releases
  • Relayer: OpenZeppelin Relayer SDK for fee-sponsored transactions

Data Flow

  • Server Components: Next.js App Router for server-side rendering
  • Client Components: React Query for client-side data fetching
  • Real-time: Supabase Realtime subscriptions
  • Caching: React Query cache + Redis for rate limiting

📝 Key Features Explained

Passkey Authentication

The app supports WebAuthn passkeys for passwordless authentication:

  • Registration flow creates a passkey and associated smart account
  • Authentication uses passkey signatures
  • Smart accounts are deployed on Stellar/Soroban

Project Management

  • Create Projects: Rich editor with TipTap, file uploads, milestones
  • Manage Projects: Team management, settings, pitch deck updates
  • Support Projects: Contribute funds via Stellar, track contributions

Escrow System

  • Funds are held in smart contract escrows
  • Milestone-based releases require verification
  • Dispute resolution system for conflicts

Admin Operations Dashboard

/admin is an action-oriented operations dashboard for platform admins:

  • Action center: pending-work queues (project reviews, missing escrows, milestone reviews, KYC cases, disputed escrows, new users) with direct resolution actions, plus platform metrics that link to pre-filtered views.
  • Server-side lists: projects, escrows, and users are searched, filtered, sorted, and paginated in the database via /api/admin/* routes guarded by requireAdminApi(). All list state lives in the URL so views can be bookmarked and shared.
  • Feature flag: the redesigned interface is gated by NEXT_PUBLIC_ADMIN_OPS_DASHBOARD (always on in development). Setting it to false in production instantly restores the legacy admin UI — the legacy components are untouched.
  • Safety: high-impact actions (milestone review decisions, campaign status changes, escrow deploy/fund/release, gamification triggers, governance round creation, backfills) require an explicit confirmation dialog that shows the state change and, for blockchain mutations, the active Stellar network and connected signer. Consequential admin actions are recorded in public.audit_logs (operations prefixed admin_*) via the server-only recordAdminAudit() helper.

KYC Verification

Identity verification powered by Didit, an AI-native identity verification platform:

  • Free Core KYC: Government ID verification across 220+ countries
  • Liveness Detection: Passive and active liveness checks to prevent fraud
  • Face Matching: 1:1 biometric verification
  • Document Verification: OCR extraction and validation
  • AML Screening: Optional advanced checks for compliance
  • Proof of Address: Address verification support
  • API Integration: Developer-first API for seamless integration
  • GDPR Compliant: Meets EU, US, LATAM, and APAC compliance standards

The verification flow can be integrated via:

  • Hosted Flow: No-code verification links
  • API Integration: Programmatic verification sessions
  • Webhooks: Real-time verification status updates

🧪 Testing

Run tests:

bun test

Test files are located in the test/ directory.

🎨 Design System

Styling

  • Tailwind CSS: Utility-first CSS framework
  • Shadcn UI: Pre-built component library
  • Custom Theme: Extended Tailwind config with brand colors
  • Typography: Geist font family

Component Structure

  • Base Components: Located in components/base/ (Shadcn UI)
  • Shared Components: Reusable components in components/shared/
  • Page Sections: Page-specific sections in components/sections/

🔧 Configuration

Next.js Config

Key configurations in next.config.ts:

  • MDX Support: Experimental MDX RS for faster compilation
  • Server External Packages: Stellar and passkey packages
  • Image Optimization: Supabase storage patterns
  • Security Headers: CSP, HSTS, X-Frame-Options

TypeScript

  • Strict mode enabled
  • Path aliases configured (~/ for apps/web/)
  • Shared types from @packages/lib

📦 Monorepo Integration

This app uses shared packages:

  • @packages/lib: Shared utilities, hooks, and services
  • @packages/drizzle: Database schema and migrations
  • @services/supabase: Supabase service configuration

🚢 Deployment

Build for Production

bun run build

Start Production Server

bun start

Environment Variables

Ensure all production environment variables are set in your deployment platform (Vercel, etc.).

📚 Learn More

🤝 Contributing

See the main README.md for contribution guidelines.

📄 License

See the main repository LICENSE file.