# Architecture

## Purpose

Open Solar Payments provides a reusable Bitcoin/Lightning payment layer for solar commerce. It turns a solar quote, product checkout, installation deposit, or workorder balance into a Bitcoin/Lightning payment request with status tracking, receipts, and settlement records.

The module is designed for emerging-market commerce where buyers, merchants, and installers need clearer payment records and better accountability across solar purchases and installations.

## Non-Goals

- It does not fund or open-source the full Suntecorb marketplace.
- It does not create an altcoin payment system.
- It does not custody customer funds by default.
- It does not replace merchant accounting, tax, or compliance systems.
- It does not require a specific Lightning provider.

## High-Level Components

1. **Merchant Application**

   The solar marketplace or merchant system that creates quotes, product carts, installation workorders, and customer records.

2. **Open Solar Payments Module**

   The open-source module responsible for payment requests, invoice orchestration, status tracking, receipts, webhook handling, and settlement records.

3. **Lightning Backend Adapter**

   A provider-specific adapter for BTCPay Server, LNbits, a Lightning node, or another Bitcoin/Lightning backend.

4. **Payment Storage**

   A database or persistence layer that stores payment requests, invoice state, receipts, settlement records, and event history.

5. **Merchant Admin Surface**

   The merchant or installer-facing view that shows payment status, receipts, order linkage, and reconciliation state.

## Flow Overview

```text
Solar quote or cart
  -> payment request created
  -> Lightning invoice generated
  -> customer pays invoice
  -> Lightning backend sends confirmation
  -> module verifies and records payment
  -> receipt generated
  -> order or workorder marked paid
  -> installer settlement record created or updated
```

## Boundaries

The open-source module owns:

- Payment request lifecycle
- Invoice metadata and status
- Webhook validation contract
- Receipt records
- Workorder settlement records
- API shape and documentation
- Provider adapter interface

The merchant application owns:

- Product catalog
- Solar sizing logic
- Quote generation
- Customer identity
- Installer onboarding
- Order fulfillment
- Private business rules

## Payment Request Lifecycle

```text
draft
  -> pending
  -> paid
  -> settled
```

Alternative terminal states:

```text
expired
failed
cancelled
refunded
```

## Invoice Lifecycle

```text
created
  -> pending
  -> paid
```

Alternative states:

```text
expired
failed
cancelled
```

## Provider Adapter Interface

The module should define a provider-neutral adapter so the rest of the system does not depend directly on one Lightning backend.

Required adapter methods:

```text
createInvoice(paymentRequest)
getInvoiceStatus(invoiceId)
parseWebhook(payload, headers)
verifyWebhook(event)
```

Optional adapter methods:

```text
refundPayment(paymentId)
listPayments(filters)
getNodeInfo()
```

## Recommended Initial Backend

BTCPay Server is a strong first compatibility target because it is open-source, Bitcoin-focused, merchant-oriented, and already familiar to many Bitcoin developers. LNbits can be considered as an additional adapter where useful.

## Security Considerations

- Webhooks must be authenticated or signature-verified where the backend supports it.
- Payment status updates should be idempotent.
- Invoice amounts should be immutable after invoice creation.
- Receipt records should not be silently overwritten.
- Settlement state changes should be logged as events.
- The module should not store seed phrases, private keys, or node secrets in application code.
- API keys and webhook secrets must be configured through environment variables or secure secret storage.

## Privacy Considerations

- Public examples should avoid personal customer data.
- Receipts should use internal customer references rather than exposing unnecessary identity details.
- Workorder settlement records should expose only the fields needed for reconciliation.
- Merchant deployments should decide what data is public, admin-only, or customer-visible.

## Suntecorb Reference Role

Suntecorb will use the module as a reference implementation by connecting payment requests to:

- Solar component carts
- Solar quote deposits
- Installation workorders
- Installer settlement records
- Customer receipts
- Admin reconciliation views

The reference implementation should prove that the module works inside a real solar commerce workflow while keeping the reusable Bitcoin/Lightning payment layer separate from Suntecorb private source code.