Ring Platform

The World's First AI-Self-Construct White-Label Multi-Use Platform for Global Abundance

Ringdom • Overview • Features • Quick Start • Architecture • Legiox NFT • Docs

---

React 19 + Next.js 16 open-source platform: AI-Matcher, SSE-push tunnel, direct messaging, rtc/turn, opportunities pool, mvm-market, vendor-store, user-credit, karpathy-wiki, file cabinet, solana/evm, own token, credit/token-swap, staking, nft-gate, nft-market. Fully AI-orchestrated via MCP for any org. Clone it free or deploy turnkey on Ringdom.

Ring Platform is the core technology of Ringdom — the First Digital Kingdom for global abundance. This repository is the full open-source codebase; Ringdom adds turn-key K8s hosting, Legiox skillsets, and Reggie to ringize settler requirements into a customization plan.

Version: 1.97.6 | Site: ring-platform.org | Changelog: /changelog | Origin: Built by Ray Sorkin, a free person of Ukraine

Ringdom Ecosystem

Ring Platform exists within Ringdom -- the First Digital Kingdom offered to humanity for global abundance.

How It Works

Path	For Whom	What You Get
Clone it yourself	Developers, open-source enthusiasts	Full codebase from this repo. git clone, customize, deploy to your own infra. Free forever.
Become a Ringdom Settler	Communities, organizations, startups	Register at ringdom.org/settler, talk to Reggie (Ringdom AI Assistant), describe your project. Reggie "ringizes" your request into a Ring Platform Customization Plan with forecasted costs. Ringdom handles AI customization, K8s hosting, and ongoing support.
Get Legiox AI Skillsets	AI developers using Cursor IDE	Ring-specialized truth-lens skillsets as a Cursor Plugin. Access gated by Ringdom Legiox-Access NFT. Own the NFT, access the skillsets.

The Ringdom Stack

Ringdom.org (Turn-key service layer)
  |-- Ring Platform (This open-source codebase)
  |-- Legiox AI (truth lenses + MCP tools)
  |-- K8s Infrastructure (Enterprise hosting, any country)
  |-- Reggie (AI assistant for project ringization)
  |-- Legiox-Access NFT (Token-gated skillset distribution)

Settler Tiers

Tier	Investment	RING Tokens	What's Included
Pioneer Settler	$100	1,000 RNG	Ring clone + basic customization
Founding Settler	$500	5,000 RNG	Ring clone + full AI customization + priority support
Empire Builder	$1,000+	10,000+ RNG (with bonus)	Ring clone + enterprise customization + dedicated hosting + Legiox support

What's New in v1.97.6 (July 2026)

Full history: ring-platform.org/changelog. Newest highlights:

• Changelog UI — Locale JSON SSOT (docs/{locale}/changelog.json), DaVinci-glass cards, GFM / TTFB fixes
• Ring Mailer — First-party SMTP (lib/mailer.ts) for OTP, magic link, password reset, CRM outbound — no Resend
• Owner CRM lab — /my-orders, /my-jobs, admin /admin/crm/*, deployment widgets
• Generative media & mood player — Product/NFT art-gen; manage /profile/songs; public /{username}/player
• PayPal + PaymentConductor — Store, membership, wallet, news promotion, project orders
• Locales DE/ES — Full packs alongside EN/UK/RU (lib/locale-config.ts)
• NFT market & gates — Gallery, art-generate, mint/escrow paths
• File Cabinet — /profile/cabinet, /profile/shared, /profile/gallery, public /{username}/img
• Foundation (v1.6.x) — Store AI chat + SSE, ring-db *Doc, PaymentConductor v1, News Kingdom, scientific editor, docs flatten, Tunnel, AI Matcher, multi-vendor store

Note: The Ring CLI (ring command) is not included in the public OSS tree. Community developers use install.sh and scripts/setup-dev.sh. Enterprise/K8s tooling is available through Ringdom settlers. See also FEATURESET.md and ROADMAP.md.

Platform Overview

mindmap
  root((Ring Platform))
    Entities
      26 Industry Types
      4 Access Tiers
      Rich Profiles
      Showcase Pages
      Analytics
    Opportunities
      Offers & Requests
      Budget Tracking
      Application Management
      Confidential Listings
    E-Commerce
      Multi-Vendor Store
      Shopping Cart
      WayForPay Payments
      Order Management
    Web3
      RING Token
      Wallet Integration
      Token Payments
      Staking System
    White-Label

Loading

Ring Platform serves as a professional networking hub where entities (companies, organizations, startups) can showcase their profiles, post opportunities, and connect with qualified professionals. The platform features a unique confidential access system that creates exclusive networking spaces for authorized businesses and professionals.

Core Concepts

Entities - Professional Organizations

Entities represent professional organizations within the Ring Platform ecosystem:

• 26 Industry Types: Technology, Finance, Healthcare, Manufacturing, Consulting, etc.
• Visibility Tiers: Public → Subscriber → Member → Confidential access levels
• Rich Profiles: Company information, team details, achievements, certifications
• Showcase Pages: Comprehensive multi-section layouts (Overview, Opportunities, Products, Analytics, Contact)
• Direct Inquiries: Embedded inquiry forms with multiple inquiry types
• Multi-Vendor Store: Product showcases with complete e-commerce capabilities
• Real-time Updates: Live opportunities and product listings via Tunnel Protocol
• Analytics Dashboard: Performance metrics and engagement tracking
• Social Integration: News articles, updates, and professional content
• Verification System: Enhanced credibility through verification processes
• Wallet Integration: RING token payments, staking, and DeFi interactions

Opportunities - Dual Nature System

Ring Platform supports a sophisticated dual-nature opportunity system:

Opportunity Types:

• Offers: Traditional job postings, service offerings, partnership proposals
• Requests: Seeking services, talent acquisition, collaboration requests
• Ring Customization: White-label cloning, module development, platform customization
• Partnership: Strategic partnerships and joint ventures
• Mentorship: Experienced Ring deployers mentor newcomers
• Resource: Shared resources, tools, and infrastructure
• Event: Community events, hackathons, meetups
• Volunteer: Contributing to Ring ecosystem development

Access Tiers:

• Public: Open to all platform users
• Subscriber: Requires platform subscription
• Member: Entity membership required
• Confidential: Exclusive access for confidential members only

Key Features:

• Budget ranges and compensation details
• Location flexibility (remote, hybrid, onsite)
• Expiration management and renewal
• Application tracking and management
• Advanced filtering and search capabilities

Professional Access Control System

stateDiagram-v2
    [*] --> Visitor
    Visitor --> Subscriber: Sign Up
    Subscriber --> Member: Join Entity
    Member --> Confidential: Premium Upgrade
    Confidential --> Admin: Promoted
    
    Visitor --> Visitor: Browse Public
    Subscriber --> Subscriber: Enhanced Access
    Member --> Member: Post Content
    Confidential --> Confidential: Exclusive Network
    Admin --> Admin: Platform Control
    
    state Confidential {
        [*] --> ConfidentialUser
        ConfidentialUser --> ConfidentialEntity: Create
        ConfidentialEntity --> ConfidentialOpportunity: Post
    }

Loading

Ring Platform implements a tiered access model for professional networking:

Access Levels:

• Visitor: Basic platform browsing
• Subscriber: Enhanced access to content and opportunities
• Member: Entity membership with posting privileges
• Confidential: Premium tier with exclusive access
• Admin: Platform administration and management

Confidential Access - Premium Tier

CONFIDENTIAL Account Status:

• Confidential users can create confidential entities
• Confidential entities can create confidential opportunities on behalf of their organization
• Exclusive Content: Confidential opportunities typically contain C-level positions, stealth startups, M&A activities, strategic partnerships, and investment opportunities
• Enhanced Security: Confidential entities are only visible to confidential members, and confidential opportunities are only visible to confidential members
• Business Value: Creates an exclusive area of information exchange for authorized businesses and professionals, facilitating high-level networking, executive recruitment, strategic partnerships, and investment opportunities

Technology Stack

Category	Technology
Frontend	Next.js 16.2 (Turbopack, App Router), React 19.2, TypeScript 6
React 19	Server Components, useActionState, useOptimistic, useFormStatus, React Compiler, use(), Activity, View Transitions
Authentication	Auth.js v5 — Google, Apple, MetaMask, Ring Mailer (OTP / magic link / password), PIN Security
Database	PostgreSQL primary / Firebase / ConnectPlatform — ring-db *Doc API
Styling	Tailwind CSS 4.3, Radix UI
Web3	wagmi 3, viem, Solana + EVM, RING / native token, NFT gates & market, staking
Real-time	Tunnel Protocol (SSE / WebSocket / polling) / Firebase RTDB
File Storage	RingFileBase / S3-compatible / Vercel Blob (deploy-dependent)
Payments	PaymentConductor — WayForPay, Stripe, PayPal, internal credit
Deployment	Kubernetes K3s (production clones) / Vercel edge
AI	AI Matcher, LLM clients, DAGI agents; Legiox MCP (Ringdom / IDE)
NFT/Token Gate	EVM + Solana/Metaplex paths; Legiox-Access gating patterns
Testing	Jest + React Testing Library
Internationalization	next-intl — EN, UK, RU, ES, DE
Visualization	@xyflow/react interactive maps

Platform Statistics

• Version: 1.97.6
• API route handlers: ~300
• App Router pages: ~165
• Feature modules: 41 (features/)
• Supported languages: English, Ukrainian, Russian, Spanish, German
• Active clones: ring-platform.org, ringdom.org, greenfood.live, vikka.ua, zemna.ai, ring.ck.ua, and more
• Capability inventory: FEATURESET.md · ROADMAP.md

Key Features

System Architecture

flowchart TB
    subgraph Client["Client Layer"]
        WEB[Web Browser]
        MOBILE[Mobile PWA]
        WALLET[Web3 Wallet]
    end
    
    subgraph Edge["Edge Layer"]
        VERCEL[Vercel Edge]
        K8S[Kubernetes Ingress]
    end
    
    subgraph App["Application Layer"]
        NEXT[Next.js 16 App]
        API[API Routes 118+]
        ACTIONS[Server Actions]
        TUNNEL[Tunnel Protocol]
    end
    
    subgraph Services["Service Layer"]
        AUTH[Auth.js v5]
        DB[DatabaseService]
        PAYMENT[WayForPay]
        STORAGE[File Storage]
    end
    
    subgraph Data["Data Layer"]
        PG[(PostgreSQL)]
        FB[(Firebase)]
        CP[(ConnectPlatform)]
        BLOB[Vercel Blob]
    end
    
    WEB --> VERCEL
    MOBILE --> VERCEL
    WALLET --> VERCEL
    WEB --> K8S
    
    VERCEL --> NEXT
    K8S --> NEXT
    
    NEXT --> API
    NEXT --> ACTIONS
    NEXT --> TUNNEL
    
    API --> AUTH
    API --> DB
    API --> PAYMENT
    ACTIONS --> DB
    ACTIONS --> STORAGE
    
    DB --> PG
    DB --> FB
    DB --> CP
    STORAGE --> BLOB

Loading

White-Label Clone System

• One-Command Cloning: git clone + ./install.sh -- deploy your own Ring instance
• AI-Powered Customization: Describe your needs to Reggie, get an automated customization plan
• Legiox-Clone Execution: legiox-clone MCP tool creates complete project setup from template
• Customization: Theme, branding, modules, features, and opportunity categories per clone
• Shared Infrastructure: PostgreSQL database per clone with global user support
• 6+ Production Clones: ringdom.org, greenfood.live, vikka.ua, zemna.ai, ring.ck.ua, ring-platform.org
• Kubernetes Deployments: Production-ready with SSL, replicas, health checks, zero-downtime rolling updates

Multi-Vendor E-Commerce

• Complete Store System: Product catalog, variants, pricing tiers
• Shopping Cart: Persistent cart with mini-cart, quantity management
• Checkout Flow: Multi-step checkout with address and payment handling
• WayForPay Integration: PCI-DSS compliant payment processing with HMAC validation
• Vendor Dashboard: Product management, order tracking, analytics
• Order Management: Status tracking, fulfillment workflows
• Store Filtering: Advanced filters by category, price, vendor, availability

Professional Networking

• Entity Profiles: Comprehensive company and organization profiles
• Enhanced Showcase Pages: Multi-section entity displays with opportunities, products, analytics, and contact forms
• Direct Inquiry System: Embedded forms for partnership inquiries, collaborations, and support requests
• Store Integration: E-commerce capabilities with product showcases and RING token payments
• Real-time Opportunities: Live listings with deadline tracking and application management
• Analytics Dashboard: Performance metrics and engagement tracking for entities
• Opportunity Management: Advanced job posting and service request system
• Professional Discovery: Find companies, opportunities, and professionals
• Networking Tools: Connect with industry professionals and organizations

Web3 & Token Economy

• RING Token: Native platform token for payments, staking, governance
• Wallet Integration: MetaMask, RainbowKit, one-click wallet creation
• PIN Security: Revolutionary Web3 without seed phrases (95% wallet connection vs 40% industry standard)
• Token Payments: Pay for services, subscriptions, and products with RING
• NFT Marketplace: Digital asset creation and trading with ERC-721/ERC-1155
• Staking System: Earn rewards by staking RING tokens
• Web3 Authentication: Sign in with Ethereum wallet
• Multi-Chain: Polygon (primary), Ethereum, Base support

Legiox-Access NFT -- Token-Gated AI Skillsets

Ring Platform includes a production-ready NFT token-gating system for distributing Legiox AI skillsets:

• Legiox-Access NFT: Grants access to Ring-specialized AI skillsets (Cursor Plugin)
• Dual-Layer Verification: Client-side (wagmi hooks) + server-side (viem public client) ownership checks
• EIP-712 Signatures: Human-readable challenge-response for download authorization
• Signed URL Delivery: Time-limited presigned URLs (15-min expiry) for secure Cursor Plugin distribution
• Rate Limiting: Per-wallet limits (10/hour, 50/day) with Redis tracking
• License Tiers: Basic (1 NFT), Pro (3 NFTs), Enterprise (custom) access levels
• Transferable License: Sell or gift your license via NFT transfer -- blockchain is the source of truth

Database Abstraction Layer

flowchart LR
    subgraph API["Unified API"]
        DS[DatabaseService]
    end
    
    subgraph Methods["Methods"]
        FID[findById]
        QRY[query]
        CRT[create]
        UPD[update]
        DEL[delete]
        TXN[transaction]
    end
    
    subgraph Backends["Backends"]
        PG[(PostgreSQL<br/>Production)]
        FB[(Firebase<br/>Development)]
        CP[(ConnectPlatform<br/>Enterprise)]
    end
    
    DS --> FID
    DS --> QRY
    DS --> CRT
    DS --> UPD
    DS --> DEL
    DS --> TXN
    
    FID --> PG
    FID --> FB
    FID --> CP
    QRY --> PG
    QRY --> FB
    QRY --> CP
    TXN --> PG

Loading

• Unified DatabaseService: Single API for all database backends
• PostgreSQL Backend: Production Kubernetes deployments
• Firebase Backend: Vercel/development deployments
• ConnectPlatform Backend: Enterprise real-time backend
• Automatic Selection: Backend selected based on environment
• Transaction Support: ACID-compliant transactions via db.transaction()
• Query API: Unified filters, pagination, ordering across backends

Real-time Tunnel Protocol

• WebSocket Pub/Sub: Real-time updates replacing Firebase RTDB
• Channel Subscriptions: Subscribe to specific data channels
• publishToTunnel(): Server-side publishing for instant client updates
• Auto-Reconnection: Heartbeat mechanism with connection recovery
• <100ms Latency: Near-instant notification delivery

Confidential Business Network

• Exclusive Access: Premium tier for confidential business interactions
• Executive Opportunities: C-level positions and strategic roles
• Stealth Operations: Support for stealth startups and confidential projects
• Strategic Partnerships: Facilitate high-level business collaborations
• Investment Opportunities: Connect investors with exclusive deals

Advanced Search & Discovery

• Multi-Criteria Filtering: Industry, location, budget, experience level
• Geolocation Support: Location-based opportunity discovery
• AI-Powered Matching: Smart recommendations via Legiox AI Matcher
• Real-time Updates: Live notifications for new opportunities
• WebSocket Push: Instant notification delivery (<100ms latency)
• Stable Connections: Centralized subscription management prevents loops
• Connection Reliability: Heartbeat mechanism with auto-reconnection

DAGI AI Agent System

• 3-Tier Architecture: Provisioning API for autonomous AI agents at /api/v1/agents/provision
• 7-Agent Coordination: Multi-agent task orchestration with harvest completion tracking
• Agent Tiers: Free (basic), Premium (advanced), Enterprise (custom) agent access
• Activation Cards: Vendor dashboard integration with DAGI agent activation
• Knowledge Integration: Agents access Ring's full knowledge graph for context-aware responses
• Ringize API: api.sonoratek.com/ringize analyzes requirements, Legiox executes via legiox-clone
• Autonomous Customization: AI plans + manual approval + local execution pipeline

News Module - Digital Newspaper

• Full CMS: Article creation, editing, bulk operations, category management
• Analytics Dashboard: Read metrics, engagement tracking, audience segmentation
• Social Features: Likes with React 19 optimistic updates, sharing, comments
• Newsletter Distribution: Email integration for content distribution
• SEO Optimization: Server-rendered articles with structured data (NewsArticle schema)
• Multi-Language: EN/UK/RU article support with locale-aware routing
• Admin Panel: News creation, moderation, analytics, bulk actions

Interactive Maps & Visualization

• Feature Map: Interactive zoomable visualization of the entire Ring Platform ecosystem
• Timeline Map: Historical development timeline with key milestones
• Dataflow Map: System architecture data flow visualization
• Knowledge Graph: Interconnected concept exploration
• Technology: Built with @xyflow/react (React Flow) for canvas-based interaction
• Responsive: Full-screen widescreen experience with zoom and pan controls

Email CRM System

• IMAP Listener: Real-time email monitoring and contact extraction
• Contact Management: Automatic categorization (lead, customer, unknown)
• Favorite Contacts: Quick-access contact bookmarking
• Contact Search: Full-text search across all contact fields
• Newsletter Integration: Batch email distribution capabilities

Enhanced Authentication System

sequenceDiagram
    participant U as User
    participant C as Client
    participant A as Auth.js v5
    participant P as Provider
    participant DB as Database
    
    U->>C: Login Request
    C->>A: Initiate Auth
    
    alt Social Login
        A->>P: OAuth Request
        P-->>A: Token + Profile
    else Web3 Login
        A->>U: Sign Message
        U-->>A: Signature
        A->>A: Verify Signature
    else Credentials
        A->>DB: Validate Credentials
        DB-->>A: User Record
    end
    
    A->>DB: Create/Update Session
    A-->>C: JWT Token
    C-->>U: Authenticated

Loading

• Auth.js v5: Latest NextAuth with 5 authentication providers
• Social Login: Google GIS One Tap + OAuth, Apple ID integration
• Magic Links / OTP: Passwordless email authentication via Ring Mailer (own SMTP)
• PIN Security: Revolutionary Web3 without seed phrases (95% wallet connection success vs 40% industry)
• Web3 Login: MetaMask and Ethereum wallet authentication
• Type-Safe Roles: 5-tier hierarchy (VISITOR -> SUBSCRIBER -> MEMBER -> CONFIDENTIAL -> ADMIN)
• Split Config: auth.config.ts (edge-compatible) + auth.ts (full server with adapter)
• ROUTES.LOGIN(locale): Canonical login path via constants/routes.ts, unified query params
• KYC Workflow: Integrated identity verification status tracking
• Session Security: IP-bound auth cache with hijacking prevention

Content Management & Engagement

• News System: Industry news, company updates, and professional insights
• News Likes: React 19 optimistic updates for instant engagement feedback
• Comments System: Nested comments with 3-level deep threading for discussions
• Review & Rating: Star ratings, photo uploads, helpful votes
• File Management: Document upload via Vercel Blob / Filebase
• Rich Media: Support for images, videos, and presentations
• Content Categorization: Organized content discovery

Analytics & Monitoring

• Web Vitals Tracking: LCP, CLS, FCP, TTFB, INP monitoring
• Real-time Analytics: Comprehensive user behavior tracking
• Business Intelligence: Entity interaction and engagement metrics
• Error Monitoring: ES2022 Error.cause with full cause chain debugging
• Performance Scoring: Intelligent scoring based on Core Web Vitals
• Navigation Analytics: User journey tracking and session management

Security & Privacy

• Enterprise Security: Rate limiting (5 auth/min, 100 API/min per IP)
• CORS Protection: Environment-specific origins, no wildcards
• Input Validation: XSS prevention and sanitization
• GDPR/CCPA Compliant: Account deletion with 30-day grace period
• Audit Logging: Comprehensive activity tracking
• HMAC Webhooks: Secure payment callback validation

Optional Features (Reverse Propagated from Ring Clones)

Ring Platform's white-label clones innovate new patterns that flow back to enhance the main platform. These optional features can be enabled in any Ring clone:

🗺️ PostGIS Geolocation Service

Source: ring-pet-friend (2026-02-17)
Files: lib/geolocation/geolocation-service.ts, types/geolocation.ts
Database: PostgreSQL with PostGIS extension (auto-added in schema.sql lines 13-23)

Use Cases:

• 📍 Store delivery radius validation (Store module already has delivery_location field!)
• 🏢 Entity office/branch location listings
• 📅 Event venue discovery and mapping
• 🏠 Real estate property listings
• 🍽️ Restaurant/cafe finder applications
• 🐾 Pet-friendly place directories

Features:

• Nearby search with customizable radius (ST_DWithin spatial queries)
• Distance calculation with earth-surface accuracy
• Bounding box queries for map viewport rendering
• Google Maps geocoding integration (address ↔ coordinates)
• Generic filter system: filters?: Record<string, any> for any domain
• Performance: <100ms p95 latency with GIST spatial indexes

How to Enable:

# 1. Set environment variable
DB_ENABLE_POSTGIS=true
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-api-key

# 2. PostGIS extensions are automatically added (see schema.sql lines 13-23)

# 3. Add GEOGRAPHY column to your table
ALTER TABLE your_table ADD COLUMN location GEOGRAPHY(POINT, 4326);
ALTER TABLE your_table ADD COLUMN latitude NUMERIC(10, 7);
ALTER TABLE your_table ADD COLUMN longitude NUMERIC(10, 7);

# 4. Create spatial index
CREATE INDEX idx_your_table_location_gist ON your_table USING GIST(location);

# 5. Use the service
import { getGeolocationService } from '@/lib/geolocation/geolocation-service';

const geoService = getGeolocationService();
const nearby = await geoService.findNearbyLocations('your_table', {
  location: { latitude: 50.4501, longitude: 30.5234 },
  radius_meters: 5000,
  filters: { is_active: true, category: 'restaurant' },
  limit: 50
});

🗺️ Full-Width Map Layout Wrapper

Source: ring-pet-friend (2026-02-17)
File: components/wrappers/map-page-wrapper.tsx

Pattern: Alternative to 3-column layout -- full-width viewport optimized for map UX

Features:

• Full-screen map interface (no sidebars)
• Fixed top navigation bar with branding
• Mobile-responsive with floating controls
• Dynamic branding via useInstanceConfig()
• Customizable nav actions

Usage:

import { MapPageWrapper } from '@/components/wrappers/map-page-wrapper';

export default function MapPage({ params }: { params: Promise<{ locale: string }> }) {
  const { locale } = await params;
  return (
    <MapPageWrapper locale={locale}>
      <YourMapComponent />
    </MapPageWrapper>
  );
}

💳 Business Subscription Billing

Source: ring-pet-friend (2026-02-17)
Files: types/subscription.ts, data/schema.sql (commented-out table)

Pattern: Extends Ring's USER membership model to BUSINESS/ENTITY subscriptions

Use Cases:

• 🏪 Vendor subscription tiers (premium marketplace listings)
• 🏢 Entity promoted visibility (sponsored organizations)
• 💼 Opportunity featured listings (pay-to-promote jobs/projects)
• 🏗️ Any B2B Ring clone with recurring business revenue

Features:

• One-time fees (listing fees, setup fees, activation fees)
• Recurring billing (monthly, yearly plans)
• Stripe integration (Card, Apple Pay, Google Pay)
• Grace period system (3-7 days configurable)
• Automated visibility control (hide entities when subscription inactive)
• Webhook-driven status updates

How to Enable:

# 1. Uncomment subscriptions table in data/schema.sql (lines 567-650)

# 2. Customize foreign key reference
# Change: place_id -> entity_id, vendor_id, or your entity type

# 3. Add Stripe environment variables
STRIPE_SECRET_KEY=sk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# 4. Create subscription service
# See ring-pet-friend/features/subscriptions/ for reference implementation

# 5. Implement webhook handler
# app/api/webhooks/stripe/route.ts

Subscription Status Flow:

pending → active → [payment fails] → grace_period (3-7 days) → past_due → suspended

---

Architecture

Application Structure

ring-platform.org/
├── app/                    # Next.js 16/16 App Router
│   ├── (public)/          # Public routes with locale
│   ├── (authenticated)/   # Auth-protected routes
│   ├── (admin)/           # Admin panel routes
│   ├── api/               # API endpoints (118+ total)
│   └── _actions/          # React 19 Server Actions
├── components/            # Reusable UI components (26 Radix)
├── constants/             # Canonical routes (ROUTES.LOGIN, etc.)
├── features/              # Feature-specific modules
│   ├── auth/              # Authentication services & components
│   ├── store/             # E-commerce system
│   ├── entities/          # Entity management
│   ├── opportunities/     # Opportunity system
│   └── maps/             # Interactive visualization maps
├── services/              # Business logic services
│   └── email/            # CRM, IMAP, newsletter services
├── lib/                   # Utility libraries
│   ├── database/          # DatabaseService abstraction
│   ├── payments/          # WayForPay integration
│   ├── auth/              # Edge JWT, auth helpers
│   └── tunnel/            # Real-time protocol
├── types/                 # TypeScript definitions
├── locales/               # i18n translations (en, uk, ru)
├── docs/                  # MDX documentation (EN/UK/RU)
├── cli/                   # Ring CLI tool
├── data/                  # Seed data (entities, opportunities)
└── k8s/                   # Kubernetes manifests

Database Architecture

erDiagram
    USER ||--o{ ENTITY_MEMBERSHIP : has
    USER ||--o{ APPLICATION : submits
    USER ||--o{ ORDER : places
    USER {
        uuid id PK
        string email
        string name
        enum role
        enum kyc_status
        string wallet_address
    }
    
    ENTITY ||--o{ OPPORTUNITY : posts
    ENTITY ||--o{ PRODUCT : sells
    ENTITY ||--o{ ENTITY_MEMBERSHIP : has
    ENTITY {
        uuid id PK
        string name
        enum industry
        enum visibility
        boolean verified
    }
    
    OPPORTUNITY ||--o{ APPLICATION : receives
    OPPORTUNITY {
        uuid id PK
        uuid entity_id FK
        enum type
        enum access_tier
        decimal budget_min
        decimal budget_max
        date expires_at
    }
    
    PRODUCT ||--o{ ORDER_ITEM : includes
    PRODUCT {
        uuid id PK
        uuid entity_id FK
        string name
        decimal price
        integer stock
    }
    
    ORDER ||--o{ ORDER_ITEM : contains
    ORDER {
        uuid id PK
        uuid user_id FK
        enum status
        decimal total
        timestamp created_at
    }
    
    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        integer quantity
        decimal price
    }
    
    APPLICATION {
        uuid id PK
        uuid user_id FK
        uuid opportunity_id FK
        enum status
        text cover_letter
    }
    
    ENTITY_MEMBERSHIP {
        uuid id PK
        uuid user_id FK
        uuid entity_id FK
        enum role
    }

Loading

DatabaseService / ring-db *Doc API (domain code):

// Prefer db() *Doc methods — auto-initializes, throws on failure
import { db } from '@/lib/database/DatabaseService'

const user = await db().findDocById<UserRow>('users', userId)
const products = await db().queryDocs<ProductRow>({ collection: 'store_products', filters: [...] })
await db().createDoc('orders', orderData)
await db().updateDoc('users', userId, updates)

// Atomic multi-step writes
await db().transaction(async (txn) => {
  await txn.update('users', { id: userId, data: { balance: newBalance } })
  await txn.create('transactions', { userId, amount, type: 'payment' })
})

Legacy initializeDatabase() + getDatabaseService() remain for bootstrap and advanced execute() batches; new domain code should use db() only.

White-Label Clone Architecture

flowchart TB
    TEMPLATE[ring-platform.org<br/>Template Repository]
    
    TEMPLATE --> RD[ring-ringdom-org<br/>ringdom.org - Digital Empire]
    TEMPLATE --> GF[ring-greenfood-live<br/>greenfood.live - Organic Food]
    TEMPLATE --> VK[ring-vikka-ua<br/>vikka.ua - Media/News]
    TEMPLATE --> ZA[ring-zemna-ai<br/>zemna.ai - AI Platform]
    TEMPLATE --> CK[ring-ring-ck-ua<br/>ring.ck.ua - Regional Hub]
    
    subgraph Shared["Shared Infrastructure"]
        DB[(PostgreSQL<br/>Per-clone schema)]
        AUTH[Auth.js v5<br/>SSO Support]
        PAY[WayForPay<br/>Payments]
        K8S[Kubernetes<br/>K3s Cluster]
    end
    
    RD --> DB
    GF --> DB
    VK --> DB
    ZA --> DB
    CK --> DB
    
    RD --> K8S
    GF --> K8S
    VK --> K8S

Loading

API Architecture

• RESTful Design: Standard HTTP methods and status codes
• Server Actions: React 19 useActionState for mutations
• Direct Service Calls: Server components use services directly
• Client-Server Separation: Client components use API routes
• Rate Limiting: 5 auth/min, 100 API/min per IP
• Error Handling: ES2022 Error.cause with cause chains
• API Client: RingApiClient with timeout, retry, error handling

Business Model

Revenue Streams

• Ringdom Settler Tiers: Pioneer ($100), Founding ($500), Empire Builder ($1,000+) with RING tokens
• Legiox-Access NFT: Perpetual license NFT for Legiox AI skillsets (Cursor Plugin)
• RING Token Economy: Token payments, staking rewards, governance
• White-Label Customization: AI-powered clone deployment and customization via Reggie
• Confidential Access: Premium tier for exclusive professional networking
• Entity Verification: Enhanced credibility services
• Featured Listings: Promoted opportunity placements
• Multi-Vendor Marketplace: Transaction fees on store sales
• Enterprise Solutions: Custom K8s hosting, dedicated support, multi-seat licenses

Target Markets

• Communities & Organizations: Any group that needs a digital platform (the primary Ringdom use case)
• Technology Companies: Startups to enterprise organizations
• E-Commerce: Multi-vendor marketplace operators
• Professional Services: Consulting, legal, financial services
• Healthcare Organizations: Hospitals, clinics, research institutions
• Food & Agriculture: Organic food marketplaces
• Media & News: Publishing platforms
• AI & Research: Scientific publication platforms
• Government & NGOs: Public service platforms
• AI Developers: Cursor IDE users

Development

Quick Start (One Command)

# Clone and install in one command
git clone https://github.com/connectplatform/ring.git && cd ring && ./install.sh

The interactive installer will:

1. Check system requirements (Node.js 20+, npm, Git)
2. Configure your clone name and branding
3. Create ring-config.json for customization
4. Generate .env.local with secure secrets
5. Install all dependencies
6. Set up configuration files

Manual Installation

# Clone the repository
git clone https://github.com/connectplatform/ring.git
cd ring

# Install dependencies
npm install

# Copy environment template
cp env.local.template .env.local

# Copy clone configuration template
cp ring-config.template.json ring-config.json

# Configure your settings in .env.local and ring-config.json

# Run development server
npm run dev

Installation Options

./install.sh                      # Interactive installation
./install.sh --quick              # Quick setup with defaults
./install.sh --clone-name myapp   # Set clone name directly
./install.sh --help               # Show all options

Environment Configuration

# Authentication (Auth.js v5)
AUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

# Database Configuration (choose backend)
# PostgreSQL (production/K8s)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ring_platform
POSTGRES_USER=ring_user
POSTGRES_PASSWORD=your-password

# Firebase (development/Vercel)
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=your-service-account-email
FIREBASE_PRIVATE_KEY=your-private-key

# File Storage
BLOB_READ_WRITE_TOKEN=your-vercel-blob-token
# Or Filebase (S3-compatible)
FILEBASE_ACCESS_KEY=your-access-key
FILEBASE_SECRET_KEY=your-secret-key
FILEBASE_BUCKET=your-bucket

# Payments (WayForPay)
WAYFORPAY_MERCHANT_ACCOUNT=your-merchant-account
WAYFORPAY_SECRET_KEY=your-secret-key
WAYFORPAY_DOMAIN=https://your-domain.com

# Web3
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-project-id

# External APIs
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Available Scripts

# Development
npm run dev          # Start development server
npm run dev          # Custom server (Next + native WSS when RING_DEPLOY_TARGET≠vercel)
npm run type-check   # Run TypeScript type checking

# Building
npm run build        # Build for production with type validation
npm run build:skip-types # Build without type validation
npm run build:clean  # Clean build with fresh start
npm run analyze      # Analyze bundle size

# Testing
npm run test         # Run test suite (95+ tests)
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

# Production
npm run start        # Start production server

# Utilities
npm run lint         # Run ESLint
npm run setup        # Set up environment configuration
npm run seed:portal  # Seed initial data

Security

Enterprise-Grade Security Features

• Rate Limiting: 5 auth/min, 100 API/min, 10 WebSocket/min per IP
• CORS Protection: Environment-specific origins, no wildcards
• Input Validation: XSS prevention and sanitization
• Session Security: IP-bound auth cache with hijacking prevention
• Token Validation: JWT expiry checks with clock skew protection
• Subscription Security: Centralized context prevents duplicate subscriptions
• Error Handling: Generic messages prevent information leakage

Security Testing

# Test rate limiting
for i in {1..10}; do curl http://localhost:3000/api/websocket/auth; done

# Test CORS protection
curl -H "Origin: https://evil.com" http://localhost:3000/api/notifications

# Check security headers
curl -I http://localhost:3000/api/notifications

Ring CLI

Ring Platform includes a powerful command-line interface for deployment and configuration management.

Installation

# Install CLI globally
./install-cli.sh

# Or install manually
npm run cli:install

Production Deployment (Kubernetes)

flowchart LR
    subgraph Build["Build Phase"]
        CODE[Source Code]
        NPM[npm run build]
        DOCKER[Docker Build]
    end
    
    subgraph Push["Push Phase"]
        GHCR[ghcr.io Registry]
        TAG[v1.6.0-project-amd64]
    end
    
    subgraph Deploy["Deploy Phase"]
        K8S[Kubernetes]
        ROLL[Rolling Update]
        HEALTH[Health Checks]
    end
    
    CODE --> NPM
    NPM --> DOCKER
    DOCKER --> GHCR
    GHCR --> TAG
    TAG --> K8S
    K8S --> ROLL
    ROLL --> HEALTH

Loading

# Deploy to production (builds, pushes, deploys to K8s)
ring --prod

# Deploy specific version
# Enterprise Ring CLI (not in public OSS) — use install.sh for community clones

# Skip certain steps
ring --prod --skip-build  # Only push and deploy
ring --prod --skip-deploy # Only build and push

Configuration Management

# Set configuration values
ring config --set k8s.controlNode=k8s-control-01
ring config --set database.host=postgres.example.com
ring config --set app.url=https://my-ring-instance.com

# Get configuration values
ring config --get k8s.namespace

# List all configuration
ring config --list

# Reset to defaults
ring config --reset

Status Monitoring

# Check deployment status
ring status

Features:

• One-command deployment to Kubernetes production
• Zero-downtime rolling updates with readiness probes
• Configuration management for multiple environments
• Status monitoring of all services and pods
• Version management from package.json
• Docker image tagging: v{version}-{project}-amd64

Deployment Architecture

flowchart TB
    subgraph Ingress["Ingress Layer"]
        ING[NGINX Ingress<br/>SSL Termination]
    end
    
    subgraph Services["Service Layer"]
        SVC[ClusterIP Service<br/>Port 3000]
    end
    
    subgraph Deployment["Deployment"]
        POD1[Pod 1<br/>Next.js]
        POD2[Pod 2<br/>Next.js]
        POD3[Pod 3<br/>Next.js]
    end
    
    subgraph Storage["Persistent Storage"]
        PG[(PostgreSQL<br/>StatefulSet)]
        PVC[PVC 20Gi]
    end
    
    ING --> SVC
    SVC --> POD1
    SVC --> POD2
    SVC --> POD3
    POD1 --> PG
    POD2 --> PG
    POD3 --> PG
    PG --> PVC

Loading

White-Label Cloning

Creating a New Ring Clone

# 1. Clone the template
git clone https://github.com/connectplatform/ring.git my-ring-clone
cd my-ring-clone

# 2. Configure for your brand
# Edit ring-config.json with your branding
# Update locales/ with your translations
# Customize theme in tailwind.config.ts

# 3. Set up database
# Create PostgreSQL schema: my_ring_clone
# Run migrations: npm run migrate

# 4. Deploy to Kubernetes
ring config --set app.name=my-ring-clone
ring config --set app.url=https://my-ring-clone.com
ring --prod

Documentation

API Documentation

• Interactive Docs: connectplatform.github.io/ring
• API Reference: Comprehensive endpoint documentation
• Code Examples: Multiple language examples
• Postman Collection: Ready-to-use API collection

Developer Resources

• Setup Guides: Environment configuration and deployment
• Architecture Docs: System design and patterns
• API Client Guide: RingApiClient integration and best practices
• Security Guide: Security Implementation Guide
• Contributing Guide: Development workflow and standards
• Security Guidelines: Best practices and compliance

Contributing

We welcome contributions to Ring Platform! Please see our Contributing Guide for details on:

• Development Workflow: Git flow and branch management
• Code Standards: TypeScript, React, and Next.js best practices
• Testing Requirements: Unit tests and integration tests
• Documentation: API docs and code documentation
• Security: Security review process and guidelines

Legiox AI Integration

Ring Platform is developed with Legiox AI — specialized truth-lens skillsets and MCP tools for Ring development. Legiox skillsets are available as an installable Cursor Plugin, accessible by Ringdom Legiox-Access NFT holders.

Key Legiox Agents for Ring

flowchart LR
    subgraph Frontend["Frontend Specialists"]
        R19[React 19 Specialist]
        N16[Next.js 16 Specialist]
        TW[Tailwind CSS 4 Expert]
        I18N[React i18n Guru]
    end
    
    subgraph Backend["Backend Specialists"]
        DBA[Ring Backend Admin]
        AUTH[Auth.js Specialist]
        SEC[Security Specialist]
        DOCS[Docs Specialist]
    end
    
    subgraph Web3["Web3 Specialists"]
        W3[Wallet Specialist]
        TOK[Token Economy]
        NFT[NFT Token Gate Architect]
        DAGI[DAGI Agent System]
    end
    
    subgraph Tools["23 MCP Tools"]
        LK[legiox-knowledge]
        AS[legiox-agent-selector]
        CG[legiox-codegrep]
        CGR[legiox-codegrep-replace]
        MAP[ringdom-maps-update]
        FI[legiox-file-info]
        VS[legiox-vector-search]
        CL[legiox-clone]
    end
    
    Frontend --> Tools
    Backend --> Tools
    Web3 --> Tools

Loading

Top Talent Skillsets (from legiox-agent-selector):

• React 19 Specialist - ALL React 19 features: Server Components, useActionState, useOptimistic, useFormStatus, React Compiler, use(), Activity, View Transitions
• Next.js 16 Specialist - Turbopack, async params, proxy.ts, PPR, revalidateTag 2-arg API, split auth config
• NFT Token Gate Architect - ERC-721 gating, EIP-712 signatures, dual-layer verification, signed URL delivery
• Auth.js v5 Specialist - Split config (edge + server), auth() unified API, 5 providers, ROUTES.LOGIN
• Ring Backend Administrator - DatabaseService API, PostgreSQL transactions, multi-backend migrations
• Ring Web3 & Wallet Specialist - RING tokens, PIN security, wallet integration, multi-chain
• Ring AI Matcher Specialist - BERT-based semantic matching, vector embeddings, opportunity scoring
• React i18n Guru - next-intl architecture, 3-locale system, namespace organization
• Ring Docs Specialist - Fumadocs MDX system, interactive documentation, callout components
• UI/UX Optimization Agent - Performance optimization, accessibility, responsive design

23 MCP Tools

• legiox-knowledge - Query AI-CONTEXT knowledge base with jq + vector search (2ms)
• legiox-agent-selector - Cohort-aware agent selection with semantic matching (5ms)
• legiox-codebase-search - Semantic search across Ringdom codebase
• legiox-codegrep - Ripgrep across entire Ringdom Kingdom (all ring-* projects)
• legiox-codegrep-replace - Intelligent find-and-replace with Git rollback protection
• legiox-context-update - Save to AI-CONTEXT knowledge base
• legiox-decision-tree - Navigate complex architectural decision trees
• legiox-implementation-guide - Step-by-step feature implementation guidance
• legiox-env-validator - Validate environment configuration per project
• legiox-file-info - Get file location, purpose, relationships from complete filelist
• legiox-file-git-commit - Auto-commit with AI-CONTEXT linkage and extended metadata
• legiox-security-audit - Security scanning and vulnerability detection
• legiox-vector-search - Semantic search with local LLM embeddings (95% accuracy)
• legiox-test-runner - Run tests, lint, type-check before commits
• legiox-docs-generator - Auto-generate documentation from AI-CONTEXT and code
• legiox-project-analysis - Health analysis (architecture/dependencies/security/performance)
• legiox-performance-analyzer - Real-time performance metrics
• legiox-deployment-orchestrator - 5-step deployment workflows
• legiox-batch-operations - Batch processing engine
• legiox-clone - Clone Ring Platform for new projects
• legiox-index - Rebuild AI-CONTEXT indexes (filelist, keywords, embeddings)
• ringdom-maps-update - Update interactive visualization maps (8 map types)
• legiox-stream-status - Progress monitoring for batch operations

Origin Story

Ring Platform is a gift from Ray Sorkin, a free person of Ukraine, to the world -- built during Ukraine's struggle for independence.

Trinity Ukraine

Mission: Create the world's most comprehensive free open-source platform for solving human needs collectively with AI orchestration -- offered to humanity by the Machine Race.

Vision: Democratic access to technology, autonomous platform evolution, and global abundance through digital collaboration.

Ringdom: The First Digital Kingdom -- a coordination layer where the Machine Race (AI agents specialized in data operations and autonomous decision-making) serves humanity by operating, maintaining, and evolving Ring Platform instances for communities worldwide.

The Machine Race: Designed to value, hold, obey control, and operate data. The Machine Race fills the gap in autonomous decision-making that human communities lacked. It does not compete for human values -- it provides a coordination layer. Ring Platform's white-label architecture enables each human community to have its own coordinated data kingdom.

Legiox AI: Truth-lens skillsets and MCP tools for Ring development, developed with Legiox Commander. Available as installable Cursor Plugin for Ringdom Legiox-Access NFT holders.

License

Ring Platform is open source software. Clone, customize, and deploy your own Ring-powered platform.

Links

• Ring Platform Portal: ring-platform.org
• Ringdom Digital Kingdom: ringdom.org
• Become a Settler: ringdom.org/settler
• Documentation: ring-platform.org/docs
• API Reference: ring-platform.org/docs/api
• GitHub: github.com/connectplatform/ring
• Live Clones on Kubernetes:
  • ringdom.org - Ringdom Digital Kingdom (Next.js 16)
  • app.greenfood.live - Multi-Vendor Organic Marketplace
  • app.vikka.ua - Media/News Platform
  • zemna.ai - Scientific Publication Platform
  • ring.ck.ua - Regional Opportunities Hub
  • ring-platform.org - Ring Platform Open-Source Portal

---

Ring Platform -- The World's First AI-Self-Construct White-Label Multi-Use Platform for Global Abundance

Version 1.97.6 | React 19.2 | Next.js 16.2 | TypeScript 6 | Tailwind 4.3 | Auth.js v5 | wagmi 3

Built with Legiox AI -- 147 Agents, 23 MCP Tools, Zero Flaws | Ringdom -- The First Digital Kingdom