Architecture Overview

Sprey is organized around a small number of independent product and infrastructure layers. Sprey Processing, available through pay.sprey.win, gives merchants their own non-custodial payment infrastructure — hosted and managed by Sprey.

Sprey Processing boundary

Sprey Processing provides managed hosting for merchant-owned, non-custodial payment infrastructure. Merchants accept payments directly to merchant-controlled wallets or payment destinations while Sprey provides software hosting, blockchain and payment-state observation, and integration infrastructure.

The product boundary is broader than WooCommerce. pay.sprey.win is intended to support the standard BTCPay merchant use cases across online and in-person payment flows:

                         SPREY PROCESSING
                         pay.sprey.win
                               |
          +--------------------+--------------------+
          |                    |                    |
       ONLINE              IN PERSON             DIRECT
          |                    |                    |
    WooCommerce              POS              Payment Requests
    other stores              QR              Payment Buttons
    integrations        phone/tablet/PC        Donations
                                               Crowdfunding
          |                    |                    |
          +--------------------+--------------------+
                               |
                          BTCPay Store
                               |
                               v
                        payment network
                               |
                               v
                  merchant-controlled wallet

API and custom integrations can connect merchant systems directly to the Processing layer without requiring WordPress or WooCommerce.

Sprey WP Stack boundary

Sprey WP Stack is one ready-made online-commerce implementation connected to Sprey Processing:

Sprey WP Stack
WordPress + WooCommerce
        |
        | BTCPay integration
        v
Sprey Processing
pay.sprey.win

WP Stack owns the WordPress/WooCommerce storefront layer. It is not required for Point of Sale, QR payment flows, Payment Requests, Payment Buttons, donations, crowdfunding, or direct API integrations.

Sprey Hub boundary

Sprey Hub is Sprey’s internal workspace under active deployment. It is intentionally separate from both the public storefront and payment infrastructure.

The target Zurich layout is:

                         SPREY
                           |
             +-------------+-------------+
             |                           |
        PUBLIC INFRA                 INTERNAL INFRA
             |                           |
         sprey-web                    sprey-hub
             |                           |
         sprey.win                  hub.sprey.win
     WordPress/WooCommerce                |
                                         +-- cloud.sprey.win
                                         |   Nextcloud Hub
                                         +-- vault.sprey.win
                                         |   Vaultwarden
                                         +-- internal dashboard
                                         +-- boards / files / calendar
                                         +-- ai.cloud.sprey.win
                                         |   LocalAI backend
                                         `-- ai.sprey.win
                                             Sprey AI Gateway

The Hub centers on Nextcloud for synchronized files and collaboration, Vaultwarden for passwords and shared credentials, and a minimal internal dashboard as the future team’s entry point. Its AI layer now uses LocalAI as the local backend and ai.sprey.win as the unified OpenAI-compatible gateway for local and external models. Sprey business mail remains on Zoho; Hub services use Zoho SMTP where outbound email is required.

The Hub also introduces a workstation-resilience goal: selected company files should live in a synchronized, structured workspace with independent encrypted offsite backup so that a clean Windows reinstall does not become a data-loss event.

See Sprey Hub — Internal Workspace Architecture for the current Hub state, security boundaries, backup model, workstation migration approach, and rollout sequence. See Sprey AI Gateway for the verified AI routing architecture.

Payment ownership

The payment itself happens independently of Sprey.

Merchant sale / order / payment request
  |
  `- asks BTCPay to create or track an invoice

Customer
  |
  `- pays independently
       |
       v
merchant-controlled wallet/payment destination
       ^
       |
BTCPay observes the Bitcoin blockchain or another configured payment network
  |
  `- determines invoice state
       |
       v
merchant-facing integration receives status

Sprey does not receive, hold, exchange, transfer, or otherwise control merchant funds.

Verification boundary

Sprey distinguishes between upstream capability and verified Sprey capability.

A feature documented by an upstream project can be part of an intended Sprey product or infrastructure scope before Sprey has configured it. It becomes a verified Sprey capability only after it is configured and tested on the reference deployment.

This preserves a clear operational rule:

Build it. Verify it. Document it.

Current reference deployment

The current Processing reference deployment is pay.sprey.win, with administrative access through adminpay.sprey.win behind Cloudflare Access. BTCPay Server runs on the dedicated sprey-btcpay host, with a synchronized pruned Bitcoin Core node and no local Lightning node in the initial reference configuration.

The initial merchant verification path is:

Bitcoin Core [verified]
        |
        v
BTCPay Store
        |
        v
merchant-controlled wallet
        |
        v
invoice
        |
        v
real customer payment
        |
        v
BTCPay network observation
        |
        v
invoice state verified

Internal components such as NBXplorer remain part of the BTCPay implementation, but they are not treated as separate merchant-facing product milestones unless troubleshooting requires component-level inspection.

Products and infrastructure roles

Domain	Product / role	Status
sprey.win	Public product site and WooCommerce storefront	Live
pay.sprey.win	Sprey Processing public payment endpoint	Live
adminpay.sprey.win	Sprey Processing administrative endpoint behind Cloudflare Access	Live
wp-stack.sprey.win	Sprey WP Stack product landing	Live
hub.sprey.win	Sprey Hub internal workspace entry point	Planned
cloud.sprey.win	Nextcloud-based internal files and collaboration	Live
bw.cloud.sprey.win	Vaultwarden password manager and secrets service	Live
ai.sprey.win	Sprey AI Gateway / OpenAI-compatible API and landing	Live
ai.cloud.sprey.win	Local AI service on Sprey Hub / Nextcloud infrastructure	Live
wallet.sprey.win	Sprey Wallet product endpoint	Planned
app.sprey.win	Customer application / control plane	Planned
rpc.sprey.win	Sprey RPC	Planned
status.sprey.win	Public service status	Planned
docs.sprey.win	Canonical documentation portal	Live

Separation of concerns

Sprey components should remain loosely coupled where practical:

Sprey Processing — managed hosting for merchant-owned, non-custodial payment infrastructure.
Sprey WP Stack — WordPress/WooCommerce storefront implementation.
Sprey Hub — internal files, collaboration, credentials, team dashboard, LocalAI, and AI-assisted workflows.
Sprey Wallet — wallet guidance and merchant custody boundary.
Sprey RPC — future independent RPC/API infrastructure.
sprey.win — public product and application layer.
docs.sprey.win — canonical operational documentation.
status.sprey.win — planned public service status layer.

A new component should be added to another product’s host only when there is a concrete operational reason. Shared branding does not require shared runtime infrastructure. In particular, internal collaboration tools should not be added to sprey-web merely because the host has spare capacity.

Engineering rule

Architecture changes should follow the smallest-correct-change principle. Prefer native product capabilities and provider-level controls before adding custom middleware, panels, monitoring stacks, or tightly coupled services.

For internal workspace data, synchronization and backup are separate responsibilities. A synchronized Nextcloud copy is not by itself a backup; recovery requires independent server-side and offsite copies plus tested restore procedures.

See Engineering Principles for the canonical Sprey engineering rules.

v1 roadmap

Finish Sprey Hub. Complete the remaining Nextcloud configuration, internal file/folder structure, workstation synchronization, access policy, and operational checks.
Complete the Hub entry layer. Build the minimal hub.sprey.win dashboard around the live Nextcloud, Vaultwarden, documentation, Processing, LocalAI, and Sprey AI Gateway services.
Stabilize and document the Sprey AI layer. The LiteLLM/PostgreSQL gateway at ai.sprey.win, OpenRouter integration, LocalAI fallback, unified sprey-assistant router, text routing, and image analysis are verified. Next AI milestones are Speech-to-Text, Text-to-Speech, backup/recovery verification, and continued documentation.
Keep Processing stable and verified. The core payment paths for BTC, USDt, Lightning/NWC, hosted subscriptions, and Payment Requests are already verified; continue testing the remaining merchant-facing BTCPay apps and integrations one flow at a time.
Finish recovery verification. Maintain independent backups for each stateful service and complete isolated restore tests, including the Hub and AI Gateway state held in PostgreSQL.
Maintain Sprey WP Stack as the reference storefront implementation. Continue validating WordPress/WooCommerce integration against Sprey Processing without coupling the storefront runtime to payment infrastructure.
Define and build Sprey Wallet MVP. Continue the non-custodial wallet track as an optional companion to Processing, with merchant-controlled keys and external-wallet compatibility preserved.
Add Sprey RPC when the current Hub and Processing work is stable. Keep rpc.sprey.win as a separate service boundary with its own availability, authentication, and monitoring model.
Add status.sprey.win and external service monitoring. Monitoring should remain independent of the services it observes.

This document should be updated when an architectural decision changes, not merely when marketing copy changes.