Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: describe the storage backend as the live media store (#1806)

Yudhi Armyndharis7bf40beb47ef
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 99de01f6f..c58813add 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -78,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Documentation
+- The README and architecture docs describe the S3 storage backend as the live media store, not a backup target.
- Document how to recover a lost admin API key without revoking the other keys.
- The integration docs say `integration_delivery_failures` holds only failed inbound deliveries.
- The webhook runbook documents the ADMIN delivery-failure redrive and no longer says failed deliveries retry on their own.
diff --git a/README.md b/README.md
index 07e9c830a..6300e7d3f 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@
**OpenWA** is a free, open-source WhatsApp API Gateway designed for developers who need full control over their messaging infrastructure—without vendor lock-in or hidden paywalls.
-Built on a **pluggable architecture**, OpenWA lets you select database engines (SQLite/PostgreSQL), backup/migration storage backends (Local/S3), and cache layers (disabled/Redis) through configuration rather than application-code changes. Message media itself is returned inline to API and webhook consumers; it is not automatically persisted to the storage backend.
+Built on a **pluggable architecture**, OpenWA lets you select database engines (SQLite/PostgreSQL), media storage backends (Local/S3), and cache layers (disabled/Redis) through configuration rather than application-code changes. The storage backend is the live store for status media and, when chat-media archiving is enabled, archived chat media; other message media is returned inline to API and webhook consumers. `scripts/backup.sh` copies only the local media directory, so an S3 bucket needs a backup of its own.
| | |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
@@ -161,15 +161,15 @@ For any deployment where ethical, legal, or regulatory compliance matters (healt
### Infrastructure
-| Feature | Status | Description |
-| ---------------- | ------ | ---------------------------------------- |
-| SQLite | ✅ | Zero-config embedded database |
-| PostgreSQL | ✅ | Production-grade database |
-| Redis Cache | ✅ | Optional performance caching |
-| S3/MinIO Storage | ✅ | Media-directory backup/migration backend |
-| Docker | ✅ | One-command deployment |
-| Health Checks | ✅ | Kubernetes-ready probes |
-| Data Migration | ✅ | Export/import between backends |
+| Feature | Status | Description |
+| ---------------- | ------ | ------------------------------------------ |
+| SQLite | ✅ | Zero-config embedded database |
+| PostgreSQL | ✅ | Production-grade database |
+| Redis Cache | ✅ | Optional performance caching |
+| S3/MinIO Storage | ✅ | Live media store (statuses, archived chat) |
+| Docker | ✅ | One-command deployment |
+| Health Checks | ✅ | Kubernetes-ready probes |
+| Data Migration | ✅ | Export/import between backends |
---
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md
index 11683c2b1..7d147db89 100644
--- a/docs/03-system-architecture.md
+++ b/docs/03-system-architecture.md
@@ -671,7 +671,7 @@ flowchart TB
end
subgraph Storage["External Storage"]
- S3[S3/MinIO<br/>Media backup / migration]
+ S3[S3/MinIO<br/>Live media store]
end
API --> S3
@@ -1307,9 +1307,10 @@ flowchart TB
Media storage is a **single service** (`src/common/storage/storage.service.ts`) that branches
internally on `storageType` — there is no `I*Adapter` interface, separate adapter classes, or a
`StorageFactory`. The two backends are `local` (the default; files under `./data/media`) and `s3`.
-The main producer/consumer is the storage export/import migration and backup flow; the status store
-also writes status media through `putFile` (under `statuses/`) and sweeps orphans back out with
-`deleteFile`. Incoming and outgoing message media is returned inline to REST/webhook consumers and is
+It is the live media store: the status store writes status media through `putFile` (under
+`statuses/`) and sweeps orphans back out with `deleteFile`, and the storage export/import endpoints
+move its contents between backends. `scripts/backup.sh` copies only the local media directory, never
+the S3 bucket. Incoming and outgoing message media is returned inline to REST/webhook consumers and is
**not** written through `StorageService` unless `CHAT_MEDIA_ARCHIVE_ENABLED=true`, which archives a copy
under `chat-media/<sessionId>/` (media this account sent also needs `CHAT_MEDIA_ARCHIVE_OUTBOUND=true`).
That copy is in addition to the inline one unless `MESSAGE_INLINE_MEDIA=archive`, which replaces the
diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.ts
index f6f64630b..147f3fd42 100644
--- a/src/common/docs-governance.spec.ts
+++ b/src/common/docs-governance.spec.ts
@@ -221,6 +221,15 @@ describe('governance docs match the repository', () => {
expect(glossary).not.toMatch(staleClaim);
});
+ // Status media lives only in the storage backend, and backup.sh never copies an S3 bucket.
+ it('describes the storage backend as the live media store, not a backup target', () => {
+ expect(read('scripts/backup.sh')).toMatch(/the bucket's contents are not archived/);
+ for (const file of ['README.md', 'docs/03-system-architecture.md']) {
+ expect(read(file)).not.toMatch(/backup\s*\/\s*migration|media backup/i);
+ expect(read(file)).toMatch(/live media store/i);
+ }
+ });
+
it('keeps the README non-affiliation disclaimer', () => {
const section = between(read('README.md'), '## Disclaimer', '\n## ');
expect(section).toMatch(/not affiliated/);