# Suntecorb Reference Implementation Plan

## Purpose

Suntecorb will be the first real-world implementation of Open Solar Payments. The goal is to prove that the open-source Bitcoin/Lightning payment module can support practical solar commerce workflows in an emerging-market context.

The reference implementation should be documented publicly while keeping Suntecorb's private marketplace code separate.

## Pilot Workflows

### 1. Solar Quote Deposit

A customer receives a recommended solar setup and quote. The customer can pay a deposit with Bitcoin/Lightning.

Expected flow:

```text
Quote accepted
  -> payment request created
  -> Lightning invoice generated
  -> payment confirmed
  -> receipt issued
  -> quote marked deposit_paid
```

### 2. Component Checkout

A customer buys solar components such as panels, batteries, charge controllers, or inverters.

Expected flow:

```text
Cart checkout
  -> payment request created
  -> Lightning invoice generated
  -> payment confirmed
  -> receipt issued
  -> order marked paid
```

### 3. Installer Booking Deposit

A customer books an installer and pays a deposit connected to the workorder.

Expected flow:

```text
Installer selected
  -> workorder created
  -> deposit payment request created
  -> payment confirmed
  -> installer settlement record created
```

### 4. Workorder Balance Payment

After installation progress or completion, the remaining balance can be paid and reconciled.

Expected flow:

```text
Workorder balance requested
  -> payment request created
  -> invoice paid
  -> receipt generated
  -> settlement status confirmed
  -> admin marks reconciled
```

## Public Reference Outputs

Suntecorb should publish:

- Screenshots or demo notes for the payment flow
- Example API calls
- Example payment request payloads
- Example receipt payloads
- Example workorder settlement payloads
- Lessons learned from real usage

No private customer data, installer data, credentials, or proprietary business logic should be published.

## Implementation Phases

### Phase 1: Documentation Alignment

- Publish this Milestone 1 documentation package.
- Link the public page to the open-source scope.
- Confirm Bitcoin/Lightning-first language.
- Confirm the module boundary from Suntecorb private code.

### Phase 2: Backend Adapter Setup

- Select BTCPay Server as first adapter target unless another Lightning backend is already available.
- Configure development provider credentials.
- Implement provider adapter contract.
- Create test invoices.

### Phase 3: Checkout Flow

- Add payment request creation from a Suntecorb quote or order.
- Add invoice creation.
- Add checkout status screen.
- Add expiry handling.

### Phase 4: Receipts and Settlement

- Generate receipt on confirmed payment.
- Connect receipt to quote/order/workorder.
- Create installer settlement record for workorder payments.
- Show admin reconciliation state.

### Phase 5: Public Demo and Lessons

- Publish demo flow notes.
- Publish payload examples.
- Publish integration lessons.
- Document limitations and next steps.

## Success Metrics

Milestone 2 and later should track:

- Number of successful test invoices
- Number of successful paid invoices
- Number of receipts generated
- Number of workorders with settlement records
- Time from invoice creation to receipt generation
- Number of integration issues found and resolved

## Open-Source Boundary

Public:

- Payment module architecture
- API contracts
- Provider adapter interface
- Example payloads
- Documentation
- Reference flow notes
- Non-sensitive demo code

Private:

- Suntecorb proprietary marketplace code
- Customer records
- Installer private records
- Internal admin credentials
- Payment provider secrets
- Business-specific scoring or pricing logic

## Grant Narrative

This reference implementation proves that the project is not theoretical. Suntecorb is already live and can test the Bitcoin/Lightning module in a solar commerce workflow. The reusable output remains open-source infrastructure for other merchants and energy platforms.