Skip to main content

​
Notifications

The notification system keeps users informed about important events and activities on the Kin Conecta platform. From new messages to booking updates and review notifications, the system ensures users stay connected and engaged.
Notifications are delivered through the platform interface with plans for email and push notification support in future releases.

​
System Overview

Notifications are event-driven messages that inform users about activities relevant to their account.

Real-time Alerts

Notifications are generated immediately when relevant events occur on the platform.

Type Categories

Different notification types for messages, bookings, reviews, and system updates.

Read Status

Track which notifications have been read with timestamps for user experience.

Entity Linking

Notifications link to related entities (messages, tours, reviews) for easy navigation.

​
Notification Structure

Each notification contains detailed information about the event: 
{
  "notificationId": 1234,
  "userId": 42,
  "type": "new_message",
  "title": "Nuevo mensaje de Ana Torres",
  "body": "Ana te ha enviado un mensaje sobre el tour en CDMX",
  "relatedEntityType": "message",
  "relatedEntityId": 567,
  "isRead": false,
  "createdAt": "2026-03-10T14:30:00",
  "readAt": null
}

​
Field Descriptions

Unique identifier for the notification. Auto-generated by the system.
The ID of the user who should receive this notification. Links notification to recipient.
Category of notification for filtering and display styling. Examples:
  • new_message: New chat message received
  • booking_request: New tour booking request
  • booking_confirmed: Booking confirmation
  • review_received: New review on your profile
  • reply_to_review: Guide replied to your review
  • match_found: New compatible profile found
  • system_update: Platform updates or announcements
Short, attention-grabbing headline summarizing the notification (60-80 characters).
More detailed description providing context about the notification event.
Type of entity the notification refers to: message, booking, review, tour, user, etc.
ID of the related entity. Used to create deep links when user clicks the notification.
Boolean flag indicating whether the user has viewed this notification.
Timestamp when the notification was generated.
Timestamp when the user marked the notification as read. null if unread.

​
Notification Types

The system supports various notification categories to cover different user interactions:

​
For Tourists

Message Notifications

  • Guide responded to your inquiry
  • New message from your guide
  • Message thread updated

Booking Notifications

  • Booking request confirmed
  • Booking request declined
  • Tour date/time changed
  • Upcoming tour reminder (24h before)

Match Notifications

  • New compatible guide found
  • Guide viewed your profile
  • Recommended guides updated

Review Notifications

  • Guide replied to your review
  • Reminder to review completed tour

​
For Guides

Message Notifications

  • New inquiry from tourist
  • Tourist responded to your message

Booking Notifications

  • New booking request received
  • Booking cancelled by tourist
  • Payment received confirmation

Review Notifications

  • New review received
  • Your review was liked
  • Average rating updated

Profile Notifications

  • Profile verification approved
  • Tourist viewed your profile
  • New compatible tourist found

​
User Experience

1

Event Occurs

A relevant event happens on the platform (new message, booking, review, etc.).
2

Notification Generated

The system creates a notification record with appropriate type, title, body, and entity links.
3

Visual Indicator

User sees a badge or counter on the notification bell icon indicating unread notifications.
4

View Notification

User clicks the notification bell to view a list of recent notifications.
5

Take Action

User clicks a notification to navigate to the related entity (message, booking, review, etc.).
6

Mark as Read

When viewed, the notification is marked as read and the counter updates.

​
Implementation Details

The notification system is implemented with:

​
Core Components

socialNetwork/src/main/java/org/generation/socialNetwork/notifications/
├── model/
│   └── Notifications.java
├── repository/
│   └── NotificationsRepository.java
└── dto/
    └── NotificationsRequest.java

​
Database Schema

CREATE TABLE notifications (
  notification_id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT NOT NULL,
  type VARCHAR(50) NOT NULL,
  title VARCHAR(255) NOT NULL,
  body TEXT,
  related_entity_type VARCHAR(50),
  related_entity_id BIGINT,
  is_read BOOLEAN NOT NULL DEFAULT FALSE,
  created_at DATETIME NOT NULL,
  read_at DATETIME NULL,
  INDEX idx_user_created (user_id, created_at DESC),
  INDEX idx_user_unread (user_id, is_read)
);
The composite index on (user_id, created_at) enables efficient queries for fetching a user’s recent notifications sorted by date. The (user_id, is_read) index optimizes unread notification counts.

​
Frontend Integration

Notifications are displayed in the user interface:

​
Notification Bell

frontend/src/styles/blocks/guide-notifications.css
Styling for the notification bell icon and badge counter visible in the header.

​
Key UI Elements

Bell Icon

Always-visible icon in the header showing notification badge with unread count.

Dropdown List

Clicking the bell reveals a dropdown with recent notifications (typically last 10-20).

Notification Item

Each notification shows icon, title, body, and timestamp. Unread notifications are highlighted.

See All Link

Link to full notifications page for viewing complete history.

​
API Patterns

While specific API endpoints are under development, typical notification operations include:

​
Get User Notifications

GET /api/notifications?userId={userId}&limit=20&offset=0&unreadOnly=false
Retrieves notifications for a specific user with pagination and filtering options.

​
Mark as Read

PUT /api/notifications/{notificationId}/read
Marks a specific notification as read and updates the readAt timestamp.

​
Mark All as Read

PUT /api/notifications/read-all?userId={userId}
Marks all notifications for a user as read.

​
Get Unread Count

GET /api/notifications/unread-count?userId={userId}
Returns the count of unread notifications for badge display.

​
Notification Delivery Channels

​
Current: In-App Notifications

Notifications are currently delivered through the web application interface. Advantages:
  • Real-time updates while user is active
  • No additional setup required
  • Rich formatting and interactive elements

​
Future: Multi-Channel Delivery

Email

Email notifications for important events (bookings, reviews) or digest of activity.

Push Notifications

Browser and mobile app push notifications for real-time alerts even when app is closed.

SMS

Critical notifications like booking confirmations or tour reminders via text message.

​
Notification Preferences

Users should be able to control their notification settings:
  • Real-time: Receive notifications immediately
  • Daily Digest: Summary of activity once per day
  • Weekly Digest: Weekly summary of activity
Users can enable/disable specific notification types:
  • Messages and inquiries
  • Bookings and confirmations
  • Reviews and replies
  • Match recommendations
  • Marketing and updates
Choose which channels to receive notifications:
  • In-app notifications
  • Email notifications
  • Push notifications
  • SMS notifications (critical only)
Critical notifications (booking confirmations, tour changes, safety alerts) should not be disabled to ensure user safety and proper platform operation.

​
Best Practices

​
For Implementation

Be Timely

Generate notifications immediately when events occur for maximum relevance.

Be Concise

Keep titles short and bodies informative but brief. Users scan notifications quickly.

Be Actionable

Always link to the relevant entity so users can take immediate action.

Avoid Spam

Don’t over-notify. Group related events and allow users to control frequency.

​
For Content

  • Use Active Voice: “Ana sent you a message” not “A message was sent”
  • Personalize: Include names and specific details
  • Create Urgency: For time-sensitive notifications (“Tour starts in 24 hours”)
  • Be Clear: Avoid ambiguity about what happened and what action is needed

​
Performance Considerations

For high-volume scenarios, consider implementing:
  • Notification batching to reduce database writes
  • Redis/cache layer for unread counts
  • Background jobs for non-critical notifications
  • Archiving old notifications (>90 days)

​
Future Enhancements

Planned improvements to the notification system:
  • Smart Grouping: Automatically group similar notifications (“3 new messages from Ana”)
  • Priority Levels: Distinguish between critical, important, and informational notifications
  • Rich Media: Include images and interactive buttons in notifications
  • Notification History: Full searchable archive of all past notifications
  • Real-time Delivery: WebSocket integration for instant in-app notifications
  • AI Summarization: AI-generated summaries for digest notifications
  • Cross-device Sync: Mark as read on one device, syncs across all devices
  • Do Not Disturb: Quiet hours scheduling to avoid late-night notifications

Related Documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us