> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.clinikally.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Asynchronous processing and data

> State stores, events, workers, and consistency boundaries.

## Event and worker model

```mermaid theme={null}
flowchart TB
  API[API services] --> SNS[SNS topics]
  API --> SQS[SQS queues]
  SNS --> SQS
  SQS --> Notify[Notify consumers]
  SQS --> StorehouseWorker[Storehouse worker]
  SQS --> OrderboxWorker[Orderbox worker]
  SQS --> GearboxWorker[Gearbox workers]
  GearboxBeat[Gearbox Celery beat] --> GearboxWorker
  GearboxWorker --> Providers[Netcore / Slack / PostHog / S3]
  SQS --> DLQ[Dead-letter queues]
```

## Event producers and consumers

| Capability                           | Evidence                                                                       |
| ------------------------------------ | ------------------------------------------------------------------------------ |
| Atlas restock/event processing       | `atlas/app/service/sqs_consumer.py`, `sns_service.py`                          |
| Vector checkout events               | `vector/README.md`, `vector/app/service/`                                      |
| Storehouse event worker              | `storehouse/app/worker_main.py`, `storehouse/app/service/storehouse_worker.py` |
| Orderbox post-order worker           | `orderbox/app/worker_main.py`, `orderbox/app/config.py`                        |
| Notify queue consumption             | `notify/app/service/sqs_consumer.py`, `notification_service.py`                |
| Gearbox schedules and Celery workers | `gearbox/celery_app.py`, Dockerfiles for worker/beat/events worker             |
| Konsilo booking SQS consumption      | `konsilo-be/src/` consultation-booking consumer                                |

## State ownership

| Store      | Services with directly evidenced use                                                                         | Typical responsibility                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| PostgreSQL | Atlas, Dermadesk, Estimo, Hodor, Konsilo, Medusa, Notify, Orderbox, Reflekt, Storehouse, Tetris              | Durable domain data and transactional state                                    |
| Redis      | Atlas, Compass, Dermadesk, Estimo, Gearbox, Hodor, Medusa, Notify, Reflekt, Sesh, Storehouse, Tetris, Vector | Cache, locks, session/OTP state, worker broker/result, and atomic reservations |
| S3         | Atlas, Dermadesk, Gearbox, Konsilo, Medusa, Orderbox, Storehouse                                             | Files, media, imports/exports, and integration payloads                        |
| SNS/SQS    | Atlas, Gearbox, Konsilo, Notify, Orderbox, Storehouse, Vector                                                | Event transport, worker delivery, and DLQ isolation                            |

## Important consistency boundaries

* **Reservations:** Storehouse uses Redis/Lua-backed atomic reservation behavior. Inspect and test reservation expiry/compensation before changing checkout or allocation behavior.
* **Commerce:** Medusa uses PostgreSQL plus Redis-backed cache, locking, event bus, and workflow facilities. Transactional assumptions should follow Medusa workflow boundaries.
* **Payments:** Mint gateway callbacks are an asynchronous boundary. Payment state must be reconciled with downstream callbacks and order status rather than relying only on client responses.
* **Notifications:** Notify is a consumer/dispatcher. Producers should publish idempotent events and preserve identifiers needed for retry and deduplication.

## Operational guidance

Every new queue producer should define a schema, idempotency key, retry policy, owner, DLQ handling path, and observable correlation identifier before deployment.