# Inovus Notifications — User Guide
Welcome. If you need in-app notifications (the kind that live in a bell icon, not fleeting toast popups) and you’re not sure where to start — you’re in the right place.
This guide is written for humans: product folks wiring a feature, app developers integrating a client, and engineers standing up or extending the service. You do not need to understand Cloudflare Workers or Cognito on day one.
Start at the top and stop when you’ve got what you need — or jump via the paths below.
# What you’ll learn
| If you want to… | Start here |
|---|---|
| Understand what this service is and whether it’s for you | What is this? |
| See the moving parts (API, client, database…) | Components |
| Know why we rebuilt this as V2 | Why V2? |
| Get something working in your app today | Getting started |
| Stand up Cognito / Supabase / Cloudflare (from scratch, including DB) | Setup |
| Use the inbox day-to-day (list, read, React, convenience API) | Everyday usage |
| Publish from a backend / background job | Publishing |
| Keep old V1 HTTP callers working | V1 compatibility |
| Go deeper (pagination, retries, metadata, polling) | Advanced usage |
| Fix 401s, duplicates, “not realtime” confusion… | Troubleshooting |
| Extend the service, run tests, read the contract | Developer reference |
# The 30-second pitch
Inovus Notifications is a shared inbox service:
- Other apps (or your own backend) publish a notification to a user.
- That user sees it in their inbox (bell dropdown, badge count, mark read, delete).
- Identity comes from the Cognito tokens you already use — no new login system.
- You get a typed npm client so you don’t hand-roll fetch, retries, and polling.
flowchart LR Producer["Your backend / M2M app"] -->|publish| API["Notifications API"] Browser["User's browser"] -->|list / subscribe| API API --> DB[(Supabase Postgres)] Browser --> Bell["Your bell UI"]
Tip: Toasts (those temporary “Saved!” banners) are not this service. Keep toast UI in your app. This service is for persistent notifications that belong in an inbox.
# Suggested reading paths
# Show a bell in my React app
- What is this? (skim)
- Getting started
- Everyday usage → React section
# Notify users when a job finishes
- Getting started
- Publishing — especially
dedupeKey - Troubleshooting if anything fails
# Migrate off old Video Library notifications
- Why V2?
- V1 compatibility
- Everyday usage → convenience API
- Full gap analysis: why-v2.md
# Deploy / operate the service
- Setup — from scratch including the database
- Detailed ops walkthrough: setup.md
- Developer reference
# Other docs (deeper / specialised)
| Doc | When you need it |
|---|---|
| Docs index | Catalogue of everything under /docs |
| AGENT.md | Copy-paste brief for a coding agent integrating V2 in an app |
| Setup guide | Full zero-to-production checklist (DB → Cognito → Worker → CI) |
| Cognito setup | Resource server, scopes, M2M clients |
| Why V2 (detailed) | Gap-by-gap comparison with V1 |
| V1 API compatibility | Exact endpoint / envelope contract |
| Storage adapters | Implementing a new database backend |
| DESIGN.md | Architecture decisions and invariants |
| Client package README | Compact API reference for @inovus-medical/notifications |
Live API docs (when the service is deployed): https://notifications.totumcloud.com/docs