ADR-004 — REST API from Day 1 for All Adapters

Status: Accepted
Date: 2026-05-21

Context

Opsome and buy2give.store share the same VPS and Postgres instance during the validation phase. A tempting shortcut: have the LunarPHP adapter read LunarPHP's database directly via a second named Eloquent connection, bypassing HTTP entirely.

Options Considered

Option	Pros	Cons
Direct DB connection (read) + internal HTTP (write)	Zero latency, no auth management	Throwaway code; only works same-VPS; buy2give.store gets special treatment
REST API from day 1	No throwaway code; buy2give.store behaves like any tenant; validates the full integration path	Requires building API routes on buy2give.store in M2

Decision

REST API from day 1, even for buy2give.store on the same VPS.

Rationale

The direct-DB approach is a false validation. If buy2give.store goes through a shortcut no other tenant uses, the adapter pattern is never proven end-to-end. When Opsome moves to a new VPS, the code would need to be rewritten anyway.

REST from day 1 means:

• buy2give.store is identical to Contact A, C, and every future tenant
• The LunarPHP adapter becomes the reference implementation for all REST-based adapters
• No migration work when Opsome moves VPS

Implementation

buy2give.store Laravel app gets an opsome-api route group:

• Protected by a per-tenant bearer token (stored encrypted in tenants.commerce_adapter)
• Exposes only the endpoints Opsome actually needs (5–6 routes)
• Network-accessible but token-protected; not network-isolated

Consequences

• M2 scope includes adding API routes to buy2give.store (1–2 extra days)
• Latency is negligible (~1ms, same VPS)
• All future adapters follow the same REST pattern