README.md

OFFER-HUB Documentation

Welcome to the OFFER-HUB documentation. This comprehensive guide covers all aspects of the project, from the Orchestrator API to the frontend architecture.

Documentation Overview

OFFER-HUB documentation is organized in two locations:

Location	Purpose	Format
/docs/	Internal developer documentation	Markdown
/content/docs/	Public web documentation	MDX (rendered at offer-hub.tech)

Quick Start

1. New to the project? Start with Project Context
2. Setting up development? Check Developer Guide
3. Contributing? Read Contributing Guide
4. AI Assistant? Read AI Context first

Core Documentation

Getting Started

• Project Context - Complete system overview and mental model
• AI Context - Essential context for AI assistants
• Developer Guide - Setup and development workflow
• Contributing Guide - How to contribute to the project

Architecture

• System Overview - System architecture and design philosophy
• Data Model - Database schema and entity relationships
• Payment Flows - Payment lifecycle and state machines
• Provider Integration - External service integrations

Guides (Internal)

• Overview - Introduction to OFFER-HUB capabilities
• Core Concepts - Key concepts and terminology
• Architecture - Technical architecture guide
• Standards - Code and API standards
• Orders - Order lifecycle management
• Escrow - Smart contract escrow
• Disputes - Dispute resolution
• Wallets - Invisible wallet system
• Deposits - Funding user accounts
• Withdrawals - Moving funds off-platform
• Events Reference - SSE and webhook events
• Errors & Troubleshooting - Error codes and solutions
• Marketplace Integration - Integration patterns
• Deployment - Production deployment
• Scaling & Customization - Advanced configuration
• AirTM Integration - AirTM payment provider
• NPM Packages - SDK publishing

Design System

• Visual DNA - Complete design language and aesthetic principles
• Neumorphism Guide - Shadow physics and elevation system
• Color Palette - Chromatic blueprint and semantic colors
• Motion & Animation - Animation standards and keyframes

Standards

• Naming Conventions - File, variable, and function naming rules
• API Contract - API response structure and error handling

Backend

• API Design - REST API design and endpoints
• Modules Overview - Core modules and responsibilities

Frontend

• Architecture - Frontend structure and patterns

Brand

• Brand Guidelines - Brand identity and usage

Business

• Product Overview - Product vision and value proposition
• Use Cases - Common marketplace scenarios
• Glossary - Terminology and definitions

Web Documentation (MDX)

The public-facing documentation is available in /content/docs/ and rendered at offer-hub.tech/docs.

Getting Started

• Introduction - What is OFFER-HUB
• Installation - Setup and installation
• Configuration - Environment variables

Guides

• Quick Start - First API call in 5 minutes
• Orders - Order lifecycle
• Escrow - Smart contract escrow
• Disputes - Dispute resolution
• Wallets - Invisible wallet system
• Deposits - Adding funds
• Withdrawals - Withdrawing funds
• Self-Hosting - Docker deployment
• Multi-Currency - Currency support

API Reference

• API Overview - REST API basics
• Webhooks - Event notifications
• Interactive API - Try the API

SDK

• SDK Quick Start - TypeScript SDK

Tech Stack

Orchestrator (Backend)

Technology	Version	Purpose
NestJS	10.x	Backend framework
Prisma	5.x	Database ORM
PostgreSQL	15+	Primary database
Redis	7+	Caching, queues, rate limiting
BullMQ	5.x	Background job processing
Stellar SDK	12.x	Blockchain integration

Monorepo (Frontend)

Technology	Version	Purpose
Next.js	15+	React framework
React	19+	UI library
Tailwind CSS	3.4+	Styling
Radix UI	Latest	Accessible components
Framer Motion	11.x	Animations

Key Concepts

Payment Flow

User deposits USDC → Creates order → Funds reserved
                                        ↓
                                   Escrow funded (on-chain)
                                        ↓
                                   Work delivered
                                        ↓
                               Release or Dispute
                                        ↓
                                   Funds transferred

Balance Model

• Available: Can be used for orders or withdrawn
• Reserved: Locked for pending orders (before escrow funding)

Authentication

• API Keys: Format ohk_live_xxx or ohk_test_xxx
• Scopes: read, write, support
• NOT JWT: API keys are stateless, no refresh tokens

ID Prefixes

Entity	Prefix	Example
User	usr_	usr_abc123
Order	ord_	ord_xyz789
Withdrawal	wth_	wth_def456
API Key	key_	key_ghi012
Dispute	dsp_	dsp_jkl345

For AI Assistants

If you're an AI assistant working on this project:

1. Read AI Context first - contains critical project information
2. Understand the dual-repo structure - Orchestrator (backend) + Monorepo (frontend)
3. API uses API Keys, NOT JWT - Important for authentication code
4. Neumorphic design system - Follow the visual DNA guidelines
5. State machines are strict - Orders/escrow follow specific state transitions

Contributing

When updating documentation:

• Keep language clear and technical
• Use code examples where applicable
• Update this index when adding new documents
• Maintain consistent formatting
• All documentation must be in English
• Web docs (MDX) must include frontmatter with title, description, order, section

External Resources

• Trustless Work - Escrow smart contracts
• Stellar Docs - Blockchain documentation
• Circle USDC - Stablecoin information