Documentation

ArayaThrust is a cloud clinic management platform built for Nigerian healthcare facilities. It is sold as a subscription in four tiers, billed in naira, with pricing based on facility size rather than patient volume.

The capabilities below are live. Each links to the section that documents it.

• Email address verification by one-time code, valid for 10 minutes.
• Subscription checkout in naira through Paystack, covering card, bank transfer, USSD and QR.
• Server-side payment confirmation by signed webhook, independent of the browser.
• Automated VAT-itemised receipts delivered over Amazon SES.
• Single-use account handoff from a confirmed payment to the customer portal.
• Contact, demo and trial enquiry delivery to the team inbox.

Electronic records, SOAP notes, pharmacy, laboratory and LIMS, HMO interconnectivity and multi-branch management are the subject of the subscription tiers and appear throughout the Features and Pricing pages. They are not yet documented here because no implementation exists in this repository to document.

• An email address you can receive mail at — receipts and the account setup link are delivered there.
• A Nigerian payment method accepted by Paystack: card, bank transfer, USSD or QR.
• A modern browser. Checkout opens Paystack in an embedded frame, so content blockers that strip third-party frames must allow it.

Registration begins on the signup page. The form collects your name, facility, email, phone and role, then sends a six-digit code to the address you entered.

If the backend cannot deliver that code, the form skips verification and continues to plan selection rather than trapping you on a step that cannot complete.

After verification you choose a tier and billing cycle, which starts a 30-day trial recorded in your browser. Converting to a paid subscription happens at checkout, and on success the platform issues a single-use link that creates your portal account with the purchased plan already applied.

The Quick Start guide walks this end to end with the exact screens in order.

Administrative settings, organisation and workspace management, user and role management, access permissions and environment configuration are functions of the customer portal at portal.arayathrust.com. The portal is a separate application and is not part of this repository, so its configuration surface is not documented here.

ArayaThrust exposes a small HTTP API that backs signup verification, transactional email, payment confirmation and the portal account handoff. It is a transactional API, not a data API: there are no read endpoints for clinical or customer records.

• Every route is POST. A GET returns 404 because no GET route is registered.
• Requests and responses are JSON, with Content-Type: application/json.
• The base URL differs per environment and is supplied to the site at build time. It appears below as {API_BASE}.

The API uses three different trust models, chosen per route by what the caller can prove.

Errors return a JSON body with an error key, for example {"error":"invalid_json"}. The webhook is the exception: it answers Paystack in plain text, because Paystack reads only the status code.

The API is throttled at the gateway at 10 requests per second sustained, with a burst allowance of 20. The limit is shared across all routes and all callers, not allocated per client. Exceeding it returns 429.

Paystack is the payment processor for all subscription billing, in naira, across card, bank transfer, USSD and QR.

The browser opens Paystack with a public key and a generated reference. It never decides whether payment succeeded. Paystack signs a charge event to the webhook, which verifies the signature, re-confirms the charge against the Paystack API, and only then records it and emails a receipt.

Because the browser chooses the amount it asks Paystack to charge, the webhook also compares the amount actually paid against every legitimate total for the claimed tier and billing cycle. A mismatch still issues the receipt and the setup link, and flags the discrepancy to the team for review.

One inbound webhook is implemented: POST /paystack/webhook, which handles charge.success and acknowledges every other event without acting on it.

• The signature is an HMAC SHA-512 of the raw request body, compared in constant time.
• Each payment reference is claimed once, so concurrent deliveries cannot send two receipts.
• That claim is released on transient failure, so a Paystack retry can complete work that a blip interrupted.
• A charge that verifies as genuinely unsuccessful keeps its claim and is not retried.

Transactional mail — verification codes, trial welcome, payment receipts and team notifications — is sent through Amazon SES on an authenticated domain, with DKIM signing and a dedicated MAIL FROM subdomain so SPF alignment is independent of the mailbox provider. Delivery events are published to a notification topic for monitoring.

Interconnectivity with NHIA-accredited HMOs is a tier feature described on the Features and Pricing pages. No integration endpoints, credentials or data contracts exist yet, so there is nothing to document. This section will carry the connection model and field mappings once they are built.

The guiding rule is that the browser is never trusted with anything that grants entitlement. Payment status comes from Paystack to the server. Plan comes from the verified charge. The account setup token is opaque and carries no claims of its own.

• Minted only after a charge is verified server-side with Paystack.
• Cryptographically random and opaque — the token encodes nothing and cannot be inspected or forged into a different plan.
• Single use. Redemption is conditional, so two simultaneous attempts cannot both succeed; the second is told the token is already used.
• Time limited, expiring automatically after seven days.
• Exchanged only server-to-server, over a shared key the browser never sees.

Signup codes are six digits, expire after 10 minutes, and are stored hashed with a server-side pepper rather than in clear text, so possession of the stored record alone does not reveal a usable code. Each record tracks its own attempt count.

• All API and site traffic is served over TLS.
• Stored records are encrypted at rest by the managed data stores that hold them.
• The Paystack secret is held as an encrypted environment value and is never present in the site bundle or in version control.
• Short-lived records — verification codes, idempotency keys, handoff tokens — carry an expiry and are removed automatically rather than accumulating.

Report suspected vulnerabilities to customercare@arayathrust.com. Please include enough detail to reproduce the issue, and allow time to remediate before any public disclosure.

Each API route runs as an isolated function with its own log stream, so a failure can be traced to a single route without affecting the others. Email delivery events are published to a notification topic, which is where bounces and complaints surface.

Paystack retries any webhook that does not return a 2xx. The webhook is written for that: work is claimed once to prevent duplicates, and the claim is released on transient failure so a retry can finish the job. A failure to send the internal team notification deliberately does not trigger a retry, because that would cost the customer a second receipt.

Durable subscription records live in managed stores with built-in redundancy, and the short-lived records expire by design rather than being backed up. A documented backup and restore procedure, with stated recovery objectives, is not yet published and will be added here when it is defined.