Outside services

Email, text messages, push notifications, card payments and file storage are the jobs our apps can't do alone: they need a mail reputation, a phone carrier, Apple and Google, a card network, or a lot of disk. We rent those, but on our terms. Each one sits behind an adapter so we can switch providers, and files go straight from the browser to storage instead of through our servers. This page describes the approach; nothing here is signed up for yet.

1. The same shape for every service

Every outside service gets one small interface in our code and one class per provider, picked by an environment variable. Rails already ships this shape for several of them (Action Mailer delivery methods, Active Storage services), so where it does, we use it rather than invent our own.

Sms.deliver(to: "+15551234567", body: "Your order is ready")
# SMS_PROVIDER=twilio | telnyx | log

The rules that come with that shape:

• Two providers, always. One we use and one we have tested, so price changes, outages or a closed account are a config change, not a rewrite.
• A local adapter for development and tests that writes to the log instead of sending. Nobody texts a real customer from a laptop.
• Our database is the record. Every message sent, charge made and file stored is a row with its organization_id and rooftop_id, so it is tenant-scoped, searchable and survives leaving the provider.
• Webhooks are verified and idempotent. Check the provider's signature, store the event id, and process it in a background job, so a retried or replayed webhook does nothing twice.
• Keys through the secrets adapter, never in code (see Secrets).
• Every call is visible. Each provider call is an OpenTelemetry span with the provider name, outcome and cost, so we can compare providers on real numbers (see Observability).

2. Files: S3-compatible storage, uploaded directly

The S3 API is the closest thing storage has to an open standard. Speaking only that API lets the same code use AWS or a server we run ourselves:

Uploads skip our servers. The app asks our server for permission, the server answers with a short-lived presigned URL, and the browser, phone app or script sends the bytes straight to storage. Our processes stay small and fast, and a 2 GB video never ties up a web worker. Rails does this out of the box with Active Storage direct uploads; elsewhere we sign the request with the aws-sdk-s3 gem, which works against any S3-compatible endpoint.

1. The client asks POST /uploads for a file name, size and type.
2. The server checks the user may upload there and returns a presigned PUT URL, or a presigned POST whose policy caps the size and pins the content type, valid for a few minutes.
3. The client uploads directly to storage.
4. The client tells the server it is done; the server checks the object exists, records it, and queues any scanning, resizing or transcoding as a background job.

Keys are tenant-scoped. The server, never the client, chooses the object key, and every key starts with the tenant, so one prefix holds everything a rooftop owns and nothing else:

org/<organization_id>/rooftop/<rooftop_id>/<uuid>/invoice.pdf

Buckets are private. Downloads use presigned GET URLs that expire in minutes, issued only after our own authorization check (see Identity). Bucket CORS allows only our origins, and a lifecycle rule deletes uploads that were started but never confirmed.

3. Email

SMTP is an open protocol, so the simplest adapter is just an SMTP setting, and Action Mailer covers the rest. Delivering mail is easy; landing in the inbox is the hard part, which is why this is one we usually rent.

• Set up SPF, DKIM and DMARC on every sending domain before the first message.
• Keep transactional mail (receipts, sign-in links) on a separate stream or domain from marketing mail, so one never hurts the other's reputation.
• Handle bounces and complaints from webhooks, and stop mailing addresses that bounce.
• Incoming mail goes through Action Mailbox, which also has adapters for these providers.

4. SMS

Text messages have to go through a carrier, so there is no self-hosted option worth having. Providers are interchangeable at the API level; the differences are price per message and coverage.

• Send only with recorded consent, and honor STOP and HELP replies.
• In the US, business texting needs 10DLC brand and campaign registration, which ties to the sending number. Keep the registration details in our records so a move to another provider is paperwork, not a surprise.
• SMS is for notifications, never for sign-in codes; it is the weakest second factor (see Identity).
• Messages cost money per segment; record the cost on each send.

5. Push notifications

Push to phones must go through Apple (APNs) and Google (Firebase Cloud Messaging); there is no way around them. We talk to them directly rather than through another broker, so there is one less company in the chain.

• Store device tokens per user and per tenant, and delete them when a provider says they are invalid.
• One notification, many channels: decide in one place whether a message goes by push, email, SMS or in-app (the noticed gem fits this well), so the channel adapters stay simple.
• Don't put private data in the push payload; it shows on lock screens. Send a short title and let the app fetch the rest.

6. Card billing

Card payments are the one service where we keep the provider at arm's length on purpose: we never see, send or store a card number. The provider's hosted checkout or card fields collect it, which keeps our PCI scope to the smallest form (SAQ A).

• Bill the organization, not the person. Plans, seats and limits attach to the tenant, and our database, not the provider, decides what a tenant may use.
• Subscriptions change through verified webhooks, processed once each.
• Saved cards are the real lock-in. Pick a gateway that will export the card vault to another PCI-compliant provider on request, and keep our own copy of customers, plans and invoices.

7. The rules

• Every outside service sits behind an adapter with at least two providers in mind and a log-only adapter for development.
• Files go straight from the client to S3-compatible storage with presigned URLs; the server picks the tenant-scoped key and authorizes every upload and download.
• Messages, charges and files are recorded in our database with their tenant.
• Webhooks are signature-checked, idempotent and handled in background jobs.
• We never handle card numbers, and never use SMS for sign-in.

These rules are section 16 of AGENTS.md, which every coding agent here follows.

Provided as is, for information only, with no warranty and no liability. Not legal or professional advice. Security and radio material is for authorized, lawful use only. Full disclaimer.

Visits are logged on our own server: IP address, browser and device details, and pages viewed. We use them to understand traffic and spot attacks, and never share or sell them.