Feature: first-class notifications module (in-app + email + optional push)

Open
#17 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
15/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
go, react
Domain
api, backend, frontend

Research direction

The first read is the existing Mailer, Asynq queue, Cache, Pulse metrics, Grit UI registry and generated React Query patterns. The proposal puts the module in internal/notify with models.Notification, notify.Send, notify.Scheduler, notify.Rule and notify.Channel; API endpoints and the useNotifications()/bell component define the surface. Done means the acceptance criteria: default models, send API with pluggable channels, hook, bell badge, and an example cron reminder. Because it is design-heavy, confirm scope with maintainers first.

Written by the indexing model from the issue text.

Description

Problem

Hand-rolled this in a Grit project and it felt like a universal pattern that belongs in the framework. Nearly every SaaS / admin app needs: in-app notification inbox (unread counter, bell icon, mark all read); email fan-out for the same event; idempotent scheduled reminders.

Grit ships the ingredients (Mailer, Asynq, Cache) but nothing that ties them together.

Proposal

Add internal/notify as a first-class battery:

notify.Send(ctx, notify.Event{
    Type: "invoice.sent",
    RecipientUserID: user.ID,
    RecipientEmail:  tenant.Email,
    Title:   "Invoice INV-202604-0042 issued",
    Message: "Amount due: UGX 1,200,000.",
    Link:    "/invoices/abc",
    Channels: notify.ChannelInApp | notify.ChannelEmail,
})
Built-in components
  • models.Notification (user-scoped, unread/read, link)
  • notify.Scheduler for delayed / recurring notifications (reminder use case)
  • notify.Rule — hook points for "when X transitions to Y, send notification Z"
  • notify.Channel interface — InApp, Email, Push, Slack — pluggable
  • Admin dashboard (Grit UI) listing recent events, delivery status, retry failed
Endpoints scaffold
  • GET /api/notifications?status=unread
  • PUT /api/notifications/:id/read
  • PUT /api/notifications/read-all
  • WebSocket/SSE endpoint for real-time push to the admin UI
Leverages existing batteries
  • Mail: existing Mailer for email channel
  • Jobs: Asynq-queued deliveries with retries
  • Cron: scheduled reminders pipeline
  • Pulse: delivery metrics

Why this is worth doing

In my rental-manager project, the reminders system (rent due 7/0/+3 days, lease renewal 30/15/0 days, dispatch worker) ended up as ~400 lines of thoughtful code that every Grit app will rewrite. Owning this in the framework means one canonical Notification schema + a proven idempotent pattern (offset_days + entity_id dedup) + a reusable NotificationBell component.

Acceptance criteria

  • Notification + Reminder models registered by default
  • notify.Send(ctx, Event) API + pluggable channels
  • React Query useNotifications() hook in generated frontend
  • Bell component in Grit UI registry with unread badge
  • Example cron-driven reminder (subscription expiring in 7 days)

Happy to port the sweep + dispatch logic from my app as a starting PR.

Dominant language
Go
Stars
152
Forks
20
Avg merge
1d 49m
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from MUKE-coder/grit

All issues in MUKE-coder/grit

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.