Background Jobs, Files, and Integrations
Work that happens without an open screen, how media is handled, and where external services enter the platform.
Some work must happen even when no staff member has the portal open. Other work
depends on files or external providers that cannot be stored as ordinary booking
fields. This part of agapi-member-booking covers those responsibilities.
Continuous checks
While the real-time service is running, it performs three regular housekeeping checks:
| Check | Business reason |
|---|---|
| Booking requests | Detect requests whose time-based state needs attention. |
| Unpaid bookings | Cancel or update bookings that stayed unpaid beyond the allowed time. |
| Socket connections | Remove inactive connections so old browser sessions do not consume capacity forever. |
These checks currently run from the long-lived process. If that process stops, the checks stop too; an HTTP health check alone should not be treated as proof that every scheduled business action ran.
Scheduler tasks
The command-line scheduler can run named tasks:
- cancel timed-out and not-paid bookings;
- send a reminder around one day before a trip;
- send a reminder for trips roughly two days ahead;
- produce the existing account-count operational email task.
Booking reminders can combine email, SMS, and push. Each channel can succeed or fail separately. A booking should not be recreated or changed merely because a reminder was not delivered.
The repository registers the tasks, but the actual production timetable belongs to deployment/scheduler configuration. A task name in PHP is not proof that it runs in every environment.
File and image handling
Files support boat photos, issue evidence, member attachments, check-in/out photos, tutorials, and generated documents.
The service can:
- accept an upload;
- store file information and return an ID;
- retrieve the original or a prepared size;
- attach file paths when business records are read;
- stream videos and create video thumbnails;
- generate a boat PDF through the fleet action.
An upload and the later business-record save are separate steps. If the second step fails, the file can be left unattached. Recovery should either attach the known file ID to the correct record or remove it through an approved cleanup process.
External services
| Service | Why the platform uses it | Failure boundary |
|---|---|---|
| PostgreSQL | Keep the shared operational history. | A database write can fail before any provider call starts. |
| Stripe | Saved payment methods, charges, invoices, and subscriptions. | Provider and local status can diverge after a partial operation. |
| Mail server | Password and booking/reminder email. | Business action can succeed while mail delivery fails. |
| SMS provider | Short reminders and operational messages. | Provider acceptance is separate from final handset delivery. |
| Push provider | App notifications and reminders. | Requires a current member device token. |
| Google Maps | Create static location images and markers. | A missing map should not make the underlying location record disappear. |
| Salesforce | Optionally enrich or synchronize member-related information and logs. | The integration can be disabled; normal core records must still work. |
| Tutorial source | Supply tutorial categories and content used by supported clients. | External content availability is separate from booking availability. |
Configuration safety
External services are selected by environment settings. Documentation should name required setting groups but never copy real keys, passwords, tokens, or provider secrets—even if an example file contains values that look usable.
Use separate development/test credentials. For payment and messaging work, confirm the environment and company/account before sending any request.
Failure investigation order
- Find the business record and the exact action time.
- Confirm whether the local save happened.
- Find the related file ID, provider ID, queue message, or delivery log.
- Compare the provider result with the local state.
- Retry only the missing step when the operation supports it.
This avoids duplicate charges, duplicate bookings, repeated broadcasts, and orphaned files.
Technical reference
The real-time routes are /ws, /upload, and /php/healthcheck.php on the
configured socket service. Scheduler startup is in agapi/php/scheduler.php and
task definitions are in agapi/php/src/app.php. File behavior is split between
the Files provider, the upload route, compatibility file traits, and video
streaming routes.