[SPIKE] Middleware PoC on DigitalOcean App Platform

[drewangell]

Spike: Middleware PoC on DigitalOcean App Platform

Description
Research and build a Proof of Concept (PoC) for a hosted PHP middleware service. This service will act as the bridge between our open-source plugins (e.g., WooCommerce, Magento) and PayPal, allowing us to securely inject platform fees and revenue share logic.

User Story

As a Product Architect, I want to validate that we can deploy our PHP SDK to a managed PaaS (DigitalOcean) and successfully process a PayPal transaction with a custom platform fee, so that we can replace our dependency on the AWS-hosted Node service with a PHP-native solution.

Acceptance Criteria

• Infrastructure Setup (DigitalOcean App Platform)

  • Create a new "App" in DigitalOcean linked to a private GitHub repository.
  • Deploy a simple index.php that outputs "Hello World" to verify the build pipeline.
  • Provision a Managed MySQL database (Dev/Basic tier).
  • Configure environment variables for PAYPAL_CLIENT_ID and PAYPAL_SECRET.

• Database Connection & Schema

  • Create a merchants table with the following columns:
    • merchant_id (Primary Key)
    • api_key (Varchar, Unique - for plugin authentication)
    • fee_rate (Decimal, e.g., 2.50)
  • Insert one test record: {'merchant_id': 1, 'api_key': 'test_123', 'fee_rate': 2.50}.

• SDK Integration

  • Install the proprietary PayPal PHP SDK via Composer.
  • Successfully authenticate with PayPal using the credentials stored in Environment Variables.

• Transaction Logic (The "Money Shot")

  • Create an endpoint POST /create-order that accepts { "amount": 100.00, "api_key": "..." }.
  • Logic must:
    1. Validate the api_key against the database.
    2. Retrieve the fee_rate for that merchant.
    3. Calculate the fee amount (e.g., $100 * 2.5% = $2.50).
    4. Construct the PayPal Order request using the SDK.
  • Crucial: Inject the platform_fees object into the transaction payload.
  • Crucial: Add the PayPal-Partner-Attribution-Id (BN Code) header.

• Validation

  • Execute a test transaction hitting the new endpoint.
  • Log the PayPal API response.
  • Confirm the returned order object contains the correct platform_fees breakdown.

Technical Notes & Risks

• Latency Check: Monitor the time it takes for the full round trip (Plugin -> Middleware -> DB -> PayPal -> Middleware -> Plugin). Target is < 2 seconds.
• Security: Ensure the Database connection string is handled via DigitalOcean "Bindable Services" or secure Env Vars, not hardcoded.
• Framework: Use a lightweight router (like Slim PHP or a simple routes.php) to avoid the overhead of a full Laravel installation for this simple service.

---

The "3-Repo Strategy"

We will treat the new service as a totally separate Application that uses the SDK as a dependency, just like any other developer would. This avoids forking the SDK and simplifies maintenance.

1. The Existing SDK Repo (your-org/paypal-php-sdk)

• Status: Keep this exactly as it is (Public).
• Purpose: It remains a pure library that knows how to talk to PayPal.
• Change Needed: None.

2. The New Middleware Repo (your-org/paypal-middleware-service)

• Status: New Private Repo.
• Purpose: This is your "PaaS" application. This is what you connect to DigitalOcean.
• How it works:
  • You initialize this repo as a fresh PHP project (composer init).
  • You run composer require your-org/paypal-php-sdk.
  • The Magic: In this code, you instantiate the SDK using your credentials (stored in DigitalOcean Env Vars), not the merchant's.
  • This repo contains the database logic (checking fee rates) and the API routes (receiving requests from plugins).

3. The Plugin Repos (your-org/woocommerce-plugin)

• Status: These are the public plugins you distribute.
• Purpose: To talk to Repo fix array with request data in MassPay #2, not PayPal.
• How it works:
  • These plugins do not need the full PayPal SDK (or if they do, only for data models).
  • Instead of calling PayPal->execute(), they use a simple HTTP client (like cURL or wp_remote_post) to send data to https://your-middleware-app.com/create-order.

Why this is better than forking

1. Single Source of Truth: When PayPal updates their API and you update your SDK (Repo 1) to fix it, your Middleware (Repo 2) gets the fix instantly just by running composer update. If you forked it, you'd have to manually merge complex code changes.
2. Security: Your Middleware repo contains your business logic (fee calculation) and database connection. You never want this mixed into a fork of a public SDK.
3. Simplicity: Your Middleware becomes very small. It’s mostly "Glue Code" that connects your Database -> Your SDK -> PayPal.

[drewangell]

The info here was provided by Gemini as a general SPIKE story. I think it's missing some details, but we'll discuss that together and fine-tune when we get to this Milestone.

[meet-creedally]

@drewangell I've been working on this task and preparing the document, whenever you've time then let me know for a call to discuss further.

[meet-creedally]

Hello @drewangell,

I have set up the middleware app locally using Local by Flywheel and implemented the create call with access token logging and API key validation against the merchants table. It is now working. Next, I need to implement it on Cloudways using form data to register the API key and make calls with proper validation.

Kindly provide the hosting details for Hosting App, so that we can test on the actual environment as well while working on the initial demo architecture.

Thanks!

PayPal_Middleware_SOW.docx

[meet-creedally]

Hello @drewangell ,

I have set up the middleware app repository structure for Cloudways in the local MAMP environment. The API key generation is implemented using a form that accepts name and email, performs proper validation, creates the API key, and stores the data in the merchant table. The fee rate is assigned and appended to the create order payload, and the create order request has been successfully tested.

I have attached the repository ZIP file for your review. Could you please verify whether the folder structure looks good to proceed? Also, could you please create the repository for the middleware?

Thanks!

paypal-middleware.zip

[meet-creedally]

Hello @drewangell,

Just wanted to check if you’ve had a chance to go through the changes.

Thanks!