Notifications System

Overview

Wishan includes a built-in notification system that supports two dispatch channels:

Architecture

notifications domain
├── core/
│   ├── entities.go     # Domain types (NotificationType, NotificationTemplate, Notification, etc.)
│   └── service.go      # Service interface
└── infra/
    ├── service.go      # Implementation (SMTP + Firebase)
    └── templates/
        ├── email.html  # HTML email layout (go:embed)
        └── in_app.txt  # In-app text layout (go:embed)

Clean Architecture

• core/ – business types and service interface (no external dependencies)
• infra/ – concrete implementation wiring SMTP, Firebase, and the database

Notification Types

Notification types are defined as a PostgreSQL enum and Go constants:

Database Tables

notification_templates

Stores customizable content for each (type, dispatcher) pair.

Default content for all 12 templates (6 types × 2 dispatchers) is inserted automatically by the database schema.

notifications

Stores individual notification instances sent to users.

user_device_tokens

Stores Firebase Cloud Messaging device tokens for push notifications.

Template Variables

Template bodies support Go template syntax (text/template). The following variables are substituted at send-time:

Example body with variables:

Congratulations {{.UserName}}! You have won the draw for {{.DrawName}}.

Storing a Notification

Call StoreNotification from anywhere in the application:

err := notificationsService.StoreNotification(ctx, notifications_core.StoreNotificationParams{
    UserID:     userID,
    Type:       notifications_core.NotificationTypeDrawWinner,
    Dispatcher: notifications_core.DispatcherEmail,
    Link:       &drawLink,
    Vars: map[string]string{
        "UserName": "John Doe",
        "DrawName": "Luxury Car Draw",
    },
})

This will:

1. Look up the template for (draw_winner, email) from the database
2. Substitute template variables in the title and body
3. Store the rendered notification in the notifications table
4. For in_app dispatchers: trigger a Firebase push notification (if device tokens are registered)
5. For email dispatchers: the email is queued (pending); the cron job sends it

Email Sending (Cron Job)

The SendPendingEmails function is called by a cron job (default: every 5 minutes) to send all pending email notifications.

• Looks up user email from users_identities where provider_id = 'email'
• Renders the notification body into the embedded email.html layout
• Sends via SMTP using github.com/jordan-wright/email
• Marks the notification as sent (sent_at = NOW())

SMTP Configuration

Add to config.yaml:

smtp:
  host: "smtp.gmail.com"
  port: 587
  username: "notifications@example.com"
  password: "your-app-password"
  from: "notifications@example.com"
  from_name: "Wishan"
  enabled: true

Set enabled: false (default) to disable email sending without errors.

Cron Schedule

cron:
  send_pending_emails_schedule: "@every 5m"  # Every 5 minutes

Firebase Push Notifications (In-App)

For in-app notifications, the system optionally sends a Firebase Cloud Messaging (FCM) push notification if the user has registered device tokens.

Device Token Registration (Mobile)

POST /device-tokens
Authorization: Bearer <firebase-token>
Content-Type: application/json

{
  "token": "<FCM registration token>",
  "platform": "android"  // "ios", "android", or "web"
}

DELETE /device-tokens
Authorization: Bearer <firebase-token>
Content-Type: application/json

{
  "token": "<FCM registration token>"
}

Admin API Endpoints

Mobile API Endpoints

Admin Panel (custom_admin)

The admin panel includes a Notifications page at /admin/notifications where admin users can:

1. View all notification templates grouped by dispatcher (Email / In-App)
2. Edit template content (subject, title, body)
3. Use template variables ({{.UserName}}, {{.DrawName}}) in the content

Navigate to Notifications in the admin sidebar.

Permissions