9fac160258
Add independent payment-service (port 8012, payment_db) with foundation licensing, BYO-PSP, merchant accounts, idempotent requests, callbacks, and immutable ledger. Co-authored-by: Cursor <cursoragent@cursor.com>
61 lines
3.0 KiB
Markdown
61 lines
3.0 KiB
Markdown
# Integration Architecture
|
|
|
|
## Inter-Service Channels
|
|
|
|
Only these channels are allowed ([ADR-001](adr/ADR-001.md)):
|
|
|
|
1. Versioned REST API
|
|
2. Webhook
|
|
3. Async Event (message bus / outbox worker)
|
|
4. Outbox/Inbox pattern
|
|
|
|
## Internal Auth
|
|
|
|
Services authenticate with **Internal Service Tokens** (hashed in `internal_service_tokens`, scoped).
|
|
|
|
## External Providers
|
|
|
|
External systems (SMS, payment, storage, tax) integrate through provider adapters registered in [provider-registry.md](../provider-registry.md). Modules must not hardcode vendor SDKs into domain services without a provider boundary.
|
|
|
|
### Current known providers
|
|
|
|
| Provider | Use |
|
|
| --- | --- |
|
|
| Payamak | SMS OTP |
|
|
| Keycloak | IdP / SSO |
|
|
| Let's Encrypt + Certbot | TLS certificates |
|
|
| S3-compatible (planned) | File storage |
|
|
|
|
## BFF Pattern
|
|
|
|
Identity & Access acts as BFF for OIDC token exchange and Keycloak theme handoff so browser secrets stay constrained.
|
|
|
|
## Frontend Integration
|
|
|
|
Frontend uses typed API clients (`lib/api.ts` primary; `lib/api-client.ts` may exist for narrower helpers). Never call databases from the browser.
|
|
|
|
## Published Resources (`publish_id`)
|
|
|
|
Every public surface that Payment, Communication, Short Link, QR, Analytics, CRM, or verticals may attach to is a **Published Resource** identified by `publish_id` ([ADR-022](adr/ADR-022.md)).
|
|
|
|
| Rule | Detail |
|
|
| --- | --- |
|
|
| Registry | Logical Publish Target Registry (`publish_id`, `tenant_id`, `resource_type`, `resource_id`, `canonical_url`, `publish_status`, `visibility`, `owner_service`) |
|
|
| Consumer key | Integrations reference **`publish_id` only** — never Experience/vertical internal tables |
|
|
| Open types | `resource_type` is an open string registry (unlimited future types) |
|
|
| Reserved URLs | `/s/`, `/p/`, `/f/`, `/survey/`, `/book/`, `/menu/`, `/card/`, `/event/` (routing not implemented by this architecture alone) |
|
|
| Published Actions | Open Action Registry — Experience binds `action_key` to `publish_id`; owning services execute |
|
|
| Public Access | Open access strategies; Experience stores policy metadata; Identity/Payment/Loyalty/Communication own auth/pay/membership/OTP |
|
|
| Universal Embed | Open embed types (iframe, SDK, widget, …); Experience owns embed metadata |
|
|
|
|
Normative docs: [published-resource-architecture.md](published-resource-architecture.md), [published-resource-contracts.md](../reference/published-resource-contracts.md), [published-action-registry.md](../reference/published-action-registry.md), [public-access-contract.md](../reference/public-access-contract.md), [embed-contract.md](../reference/embed-contract.md).
|
|
|
|
## Related Documents
|
|
|
|
- [Event-Driven Architecture](event-driven-architecture.md)
|
|
- [Published Resource Architecture](published-resource-architecture.md)
|
|
- [Provider Registry](../provider-registry.md)
|
|
- [Provider Reference](../reference/provider-reference.md)
|
|
- [Services Contracts](../reference/services-contracts.md)
|
|
- [Published Resource Contracts](../reference/published-resource-contracts.md)
|