Decision log
Every v1 design decision, whether it is settled, and where it is explained.
Decided
| Area | Decision | Details |
|---|---|---|
| Product | Our own ntfy-like service, not a layer on top of ntfy | Scope |
| Audience | You plus invited users on one deployment | Access |
| Sign-up | Invite links only; public sign-up is off | Access |
| Model | Project → Feature → Notification model everywhere: database, API, push payload (version 2), app and docs. Every conversation is a feature; messages without one go to the project-level thread | Data model |
| Sharing | Membership per project with owner, publisher, subscriber roles | Access |
| Publish auth | Bearer access tokens, scoped to all projects or a list | Access |
| Token storage | notifier's own access_token table, not the better-auth api-key plugin | Access |
| API style | Our own API, not compatible with ntfy | API overview |
| v1 features | HTTP publish and history, phone push, action buttons, attachments | Scope |
| Live web view | Not in v1, so no Durable Objects yet | Scope |
| Retention | 30 days by default, configurable per project | Retention |
| Actions | Open URL, HTTP request, reply / acknowledge | Publish |
| Platform | Android first; iOS kept possible | Mobile |
| App stack | Expo + React Native with native pieces where they matter | Mobile |
| UI | HeroUI Native components only, the same on both platforms | Mobile |
| Push path | The Worker calls FCM HTTP v1 directly with data-only messages | Push delivery |
| App ID | com.bartuozel.pocketnotifier for the Android package and iOS bundle | Android setup |
| Background receiving | A small Kotlin FirebaseMessagingService in an Expo module, not a JS background task | Push delivery |
| Channels | One Android channel per priority, five in total | Notifications |
| Grouping | Notifications stack per project | Notifications |
| Tap | Opens the message's thread: its feature, or the project-level thread | Notifications |
| Navigation | Three native tabs: Inbox, Projects, Settings | Navigation |
| Main use case | Coding agents in T3 Code notify when done, blocked or failing | Coding agents |
| Agent entry point | A remote MCP server at /mcp is the primary path; agent-notify over REST stays as the fallback | MCP server |
| Project and feature | A project is a product or repository; a feature is a workstream in it, shown as a conversation; feature status active, done, archived | MCP server |
| General project | Notifications without a project go to a private, per-user General project, created on first need | MCP server |
| Feature auto-create | Sending to a feature that does not exist creates it from the given name | MCP server |
| MCP sign-in | OAuth 2.1 with PKCE and dynamic client registration, from better-auth's MCP provider; sign-in and consent pages served by the Worker | MCP server |
| Agent layout | With MCP each repository is a project and each feature a conversation; with REST, one agents project | Coding agents |
| Avatars | Project avatar with agent badge, chat-style (MessagingStyle) | Notifications |
| Avatar source | Generated initials and color; an HTTPS iconUrl overrides | Notifications |
| Answering agents | Agents can ask with a reply action; they cannot read replies through MCP yet | MCP server |
Open
Proposals that are written into the contract or the docs but still need a yes or no.
| Question | Proposal | Details |
|---|---|---|
| Attachment size cap | 15 MB per file | Publish |
| Secrets in HTTP actions | Not supported: HTTPS URL, method and body only, no headers | Publish |
| Waiting for a reply | Not in v1; scripts poll GET /v1/messages/{id}/responses | Messages |
| Publishing to a missing project | Rejected with 404; projects are created in the app | Publish |
| Project names | Unique across the whole deployment | Data model |
| Actions per message | Up to 5; the first 3 appear on the notification | Notifications |
| Read sync | A dismiss push clears notifications on other devices after a message is read | Push payload |
| Rate limits | Per token: 60 messages a minute, 1,000 a day | Errors |
| Agent thread URL | How agents get their T3 Code thread URL for clickUrl | Coding agents |
| Project icons | Where real project icons come from (GitHub avatar, favicon) | Coding agents |
| iOS push | FCM to APNs, or APNs directly, decided when iOS work starts | Push delivery |
Later
- Live delivery to the web dashboard (Durable Objects and WebSocket).
- An always-on connection for phones without Google Play services.
- Server-side HTTP actions that can hold secrets.
- Teams or workspaces above projects.