Problem and context

Over time, our communication stack has grown organically across multiple tools, delivery channels, and implementation paradigms. As a result, we now face the following challenges:

<aside> 💡 Fragmentation: Communication to users happens via banners, push notifications, OneSignal journeys, in-app cards, emails, and surveys—all with different data sources, logic, storage, and rendering mechanisms.

Duplication and Redundancy: Some messages are sent through multiple channels simultaneously often with inconsistent content or tone.

Poor Maintainability: Some systems rely on brittle implementations or schema-less migrations for push messages. Others require manual PRs to deliver updates.

Inefficient Targeting: There’s no shared system of targeting or segmentation across all communication channels, which limits personalization and leads to user fatigue.

Limited Observability: There is no unified place where users can see what messages they've received or dismissed, nor any clear audit trail for internal teams. (we have logs but not sure folks know how to check them or filter them?)

Inconsistent UX and Tone: Each channel looks and feels different, with no unified design system or voice. Learn and Manage handle UI logic differently for the similar message types (e.g., in-app notifications).

Hard to Scale: Adding new campaigns or flows requires one-off logic and duplication of work across product, design, and engineering.

</aside>

Characterization and Summary of Communication Systems

➡️ Systems for Sending Information

• See all

⬅️ Systems for Receiving Information from Users

• See all

Proposal

here you can find the diagram

We propose building a centralized Messaging Infrastructure Layer, consisting of:

1. Shared messages Table

• Canonical source for all user-facing messages (announcements, notifications, feature updates, banners, surveys, etc. - except for activities feedbacks and Global Static Banners, this will continue to be isolated).
• Fields include: id, created_at, updated_at, cta, created_by, source (learn, manage, teach).
• index table by source

• With the following supporting schema:

  + A message_contents Table

  • Index table by type_id
  • content can be a JSON that houses either the default information (title, body, etc.) but also other extra, like images, or even a component
  • Distinct message_contents can belong to a same message_id, this way we have the user dismiss all message_contents from the same messages source (prevents upsetting user with spamming)

  id	timestamps	type_id	content	message_id
  1	…	3	{…}	1
  2	…	2	{…}	1
  3	…	2	{…}	2

  + A message_types Table

  • delivery_channel specifies the channel in which the message type should be sent, e.g. we can have multiple notification types but there are different channels (OneSignal, in-app) for each type;
  • The snooze field represents whether 1. the message type can be dismissed (and show up later); 2. how much time the message will show up again after being dismissed (if not past the actionable_until date)

  id	timestamps	name	delivery_channel	snooze (hours)
  1	…	notification	OneSignal	<null>
  2	…	notification	in-app	<null>
  3	…	nps survey	in-app	48
  4	…	notify-lessons	targeted-banner	<null>

  + A message_targets Table

  • Target audience from each message.
  • We can track state of message creation with a creating flag.
  • target_type represents which class type target_id belongs to (organization, segment …) → no users, since this would trigger a bunch of messages queueing up. Specifically for the *all* type, we'll implement safeguards to permit only specific message types to send this kind of message (ui-only banners, for example)
  • actionable_until is the field that specifies the message_targets’ expiration date, it's important, for example, in cases where we always reuse a same old message but on different periods of time (e.g. "Your Graduation Test is ready!” but on different graduations, so we need different expiration dates). This field will have a default date (something like 14 days from now);
  • We'll also have a cronjob that runs hourly to send scheduled messages according to starts_at data (to support this, we'll also implement backoff handling + missed-job recovery logic).

  id	created_at	updated_at	starts_at	actionable_until	message_id	target_type	target_id
  1	…	…	<null>	<null>	1	segment	1
  2	…	…	20th June	30th June	1	organization	250
  3	…	…	<null>	<null>	2	segment	2
  4	…	…	20th June	30th June		all	<null>

  + A message_segments table

  • Segments (tag-based) will be created when a request is filled in the manage app. This way, we can audit their query requests and create views accordingly (and change them as needed, considering major changes like deprecation) - these will be the default segments (will show up as options);
  • Heavier queries will be handled with ClickHouse;
  • We'll also have basic base segments that can optionally have filters applied to, which will help with more flexibility on segment selection (these are not default);
  • Cache for storing already queried segments (specifically tag-based ones, since they'll be few and we can update the cache according to model changes as callbacks in rails).

  id	timestamps	default	slug	user_ids_query	type
  1	…	true	premium_users	“SELECT DISTINCT users.id FROM users INNER JOIN classrooms_licenses ON classrooms_licenses.user_id = users.id INNER JOIN classrooms_offerings ON classrooms_offerings.id = classrooms_licenses.offering_id AND classrooms_offerings.active WHERE classrooms_offerings.name in ('Premium') AND (classrooms_licenses.ends_at > current_timestamp)”	sql
  2	…	true	premium_and_closed_premium_users	“SELECT DISTINCT users.id FROM users INNER JOIN classrooms_licenses ON classrooms_licenses.user_id = users.id INNER JOIN classrooms_offerings ON classrooms_offerings.id = classrooms_licenses.offering_id AND classrooms_offerings.active WHERE classrooms_offerings.name in ('Premium', 'Closed Premium') AND (classrooms_licenses.ends_at > current_timestamp)”	sql
  3		true	pending_graduation_test_users	“`SELECT users.id FROM users INNER JOIN tests ON tests.user_id = users.id INNER JOIN test_collections ON test_collections.id = tests.collection_id WHERE (tests.expires_at > current_timestamp) AND tests.started_at IS NULL AND tests.ended_at IS NULL AND tests.recreated_at IS NULL AND tests.cancelled_at IS NULL AND tests.score IS NULL AND (test_collections.name = 'Class assessment %' **
  4		false	slang_premium	{”organization_id”: 1,
  ”fields”: {
  ”table”: …, “join_users_on": “id”, “join_table_on”: “user_id”, “field_1”: {…}, “field_2”: {…}
  }}	json

  + A user_message_logs Table

  • Tracks user-based action e.g. reads, dismissals… (like it was done in user_event_logs for some dismissals prior).

  • This information will be stored in Clickhouse instead of Postgres;

  • With indexed message_target_id and user_id for faster querying.

  • Data source for in-app reports and analytics.

  • Some event options include: dismissed (will be sent again according to the corresponding message_types’ snooze), read, pinned, filled, unpinned.

    id	timestamps	user_id	message_target_id	event
    1	…	763212	1	dismissed
    2	…	763212	2	read
    3	…	763212	1	pinned
    4	…	763212	1	filled

  about feedbacks:

  we'll keep user submissions in their respective current tables, but the 'sending’ logic will be held by the process and schemas we described above.

2. A Delivery Routing Engine

• Encapsulates logic for which messages get delivered to which users and how (push, in-app, email, etc.).