# Bills Service Unit

> Centralised billing, wallet, and currency management platform for the three enterprises within the United Communities of Feking ecosystem.

Bills Service Unit (Chinese: 賬單服務部) is the unified financial platform for the United Communities of Feking ecosystem. It consolidates billing and account management across three enterprises: ByArts Limited (art support), HW & YZ LLP (financial services), and POSHIM LLC (technology platform). The platform supports six currencies: three platform tokens (HoM, Dinner, UNCIA) and three fiat currencies (GBP, USD, HKD). Users manage multi-currency wallets, subscribe to VIP memberships, exchange currencies, invest in asset portfolios, top up accounts via Stripe, and view transaction histories from a single dashboard. Authentication is handled via SUUD (suud.net), the ecosystem's identity provider.

## About

Bills Service Unit is operated by Vector Lab. (矢量實驗室, https://vrh.cc) as the financial infrastructure for the United Communities of Feking. It serves as the single point of entry for all monetary interactions with ecosystem enterprises. Each of the three supported enterprises has its own VIP membership tiers and billing configuration, but they are all managed through this unified platform. The service integrates with Stripe for fiat currency payments and provides real-time exchange rates between platform tokens and fiat currencies.

## Pages

- **/en** and **/zh** — Home page describing the enterprise billing solution, listing the three supported enterprises (ByArts Limited for art support, HW & YZ LLP for financial services, POSHIM LLC for technology platform), core features (currency management, portfolio management, enterprise integration), platform overview statistics (3 enterprises unified, 6 currencies supported, 1 unified dashboard), frequently asked questions, and contact information (email and Discord community)
- **/en/auth** and **/zh/auth** — Authentication page for signing in via SUUD OAuth; supports browsing as guest; describes SUUD as the unified authentication system with enterprise-grade encryption
- **/en/dashboard** and **/zh/dashboard** — Main user dashboard with multiple sections:
  - Statistics overview showing total assets value, platform currency balance, and fiat balance with day-over-day change
  - Portfolio overview with wallet balances across all six currencies and asset portfolio positions (Stability Fund, Profitability Fund, Liquidity Fund) showing total value, units, and locked amounts
  - Top-up services for depositing funds via Stripe into any of the three enterprise accounts
  - Trading centre with currency exchange (convert between any supported currencies with real-time rates) and asset investment (purchase fund units with platform or fiat currencies)
  - VIP membership management showing current VIP status, days remaining, level selection, duration selection (1-12 months), and subscription via Stripe
  - Recent transaction history with filtering by type (deposit, withdrawal, currency exchange, asset investment, VIP trial, asset purchase/sale/conversion, VIP purchase, top-up) and status (pending, completed, failed, cancelled)
- **/en/success** and **/zh/success** — Payment success confirmation page showing order details (service provider, amount, currency, payment type) for VIP subscriptions and top-ups
- **/en/cancel** and **/zh/cancel** — Payment cancellation page confirming no charges were made, with option to return to dashboard

## Features

- **Multi-enterprise billing consolidation**
  - ByArts Limited (人生如藝) — Art support services
  - HW & YZ LLP (匯萬盈兆) — Financial services and market analysis
  - POSHIM LLC (浦深時明) — Technology platform and productivity tools
  - Each enterprise maintains independent VIP tiers and billing configuration
- **Multi-currency wallet system**
  - Platform tokens: HoM (Hairpins of MomijidaniRisa), Dinner, UNCIA
  - Fiat currencies: GBP (British Pound), USD (US Dollar), HKD (Hong Kong Dollar)
  - Per-currency balance tracking with locked balance support
  - Real-time exchange rates sourced from external APIs with caching
- **Currency exchange**
  - Convert between any pair of the six supported currencies
  - Real-time exchange rate display during conversion
  - Available balance shown for the source currency
  - Transaction recorded with exchange rate and fee details
- **Asset investment**
  - Three fund types: Stability Fund, Profitability Fund, Liquidity Fund
  - Purchase fund units using platform tokens or fiat currencies
  - Track total value, unit count, and locked positions
- **VIP membership subscriptions**
  - Per-enterprise VIP levels with tiered benefits (Basic, Premium, Elite)
  - Subscription durations from 1 to 12 months
  - Payment processing via Stripe checkout
  - Active status tracking with days remaining countdown
  - 7-day VIP trial offered as a registration bonus for each enterprise
  - Benefits include lower trading fees, priority support, advanced tools, and higher withdrawal limits
- **Fiat top-up via Stripe**
  - Stripe-integrated payment flow for depositing fiat currency
  - Per-enterprise Stripe configuration with separate API keys
  - Success and cancellation handling with redirect pages
- **Transaction history**
  - Complete record of all financial activities
  - Filterable by transaction type and status
  - Types: deposit, withdrawal, currency exchange, asset investment, VIP trial, asset purchase, asset sale, asset conversion, VIP purchase, top-up
  - Statuses: pending, completed, failed, cancelled
- **Portfolio overview**
  - Total assets value calculation across all currencies and funds
  - Wallet balances for each currency
  - Asset positions with unit counts and locked amounts
  - Day-over-day change tracking for total balance, platform balance, and fiat balance

## Technical Details

- Built with TanStack Start, React 19, Vite, and Nitro
- Bilingual: English (en) and Traditional Chinese - Hong Kong (zh)
- Database: SQLite via bun:sqlite with Drizzle ORM
- Authentication: Better Auth with SUUD OAuth (OAuth2 authorisation code flow)
- Payment processing: Stripe (server-side stripe package, client-side @stripe/stripe-js)
- Data models: users, sessions, accounts, verification tokens, businesses, user-business associations (with VIP level), user wallets (per-currency balances), transactions, VIP subscriptions, top-up records, user statistics (daily snapshots), Stripe configurations (per-business), external API configurations, system configurations, currency rates
- API endpoints:
  - /api/auth/oauth2/callback/suud — SUUD OAuth callback
  - /api/auth/sync — Session synchronisation
  - /api/dashboard — Dashboard data aggregation (stats, portfolio, wallets, transactions)
  - /api/businesses — Enterprise listing
  - /api/data — Market data and exchange rates
  - /api/exchange — Currency exchange execution
  - /api/invest — Asset investment execution
  - /api/membership — VIP subscription management
  - /api/stripe/subscribe — Stripe checkout session creation for VIP and top-up
  - /api/topup — Top-up record management

## Related Services

- SUUD (https://suud.net) — Authentication provider (required for sign-in)
- United Communities of Feking (https://ucf.plus) — Community hub and governance
- Round Table (https://2b.chat) — Discussion forum and voting
- ByArts (https://byarts.uk) — Art gallery platform (billing managed here)
- HW & YZ (https://hwyz.uk) — Financial analysis platform (billing managed here)
- POSHIM (https://poshim.com) — Productivity platform (billing managed here)
- Vector Lab. (https://vrh.cc) — Technical infrastructure provider

## Contact

- Website: https://bills.su
- Parent organisation: Vector Lab. (https://vrh.cc)