Docs/improve broadcast guide (supabase#39526)

* clarify how the private/public flags work in Realtime Broadcast

* Update apps/docs/content/guides/realtime/broadcast.mdx

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* quick fixes on documentation

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update apps/docs/content/guides/realtime/broadcast.mdx

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* fix format

* the lost them

---------

Co-authored-by: Monica <[email protected]>
Co-authored-by: Monica Khoury <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

apps/docs/content/guides/realtime/broadcast.mdx

@@ -6,6 +6,27 @@ description: 'Send low-latency messages using the client libs, REST, or your Dat
 
 You can use Realtime Broadcast to send low-latency messages between users. Messages can be sent using the client libraries, REST APIs, or directly from your database.
 
+## How Broadcast works
+
+The way Broadcast works changes based on the channel you are using:
+
+- From REST API will receive an HTTP request which then will be sent via WebSocket to connected clients
+- From Client libraries we have an established WebSocket connection and we use that to send a message to the server which then will be sent via WebSocket to connected clients
+- From Database we add a new entry to `realtime.messages` where we have logical replication set to listen for changes which then will be sent via WebSocket to connected clients
+
+<Admonition type="note">
+
+The public flag (the last argument in `realtime.send(payload, event, topic, is_private))` only affects who can subscribe to the topic not who can read messages from the database.
+
+- Public (false) → Anyone can subscribe to that topic without authentication
+- Private (true) → Only authenticated clients can subscribe to that topic
+
+However, regardless of whether it's public or private, the Realtime service connects to your database as the authenticated Supabase Admin role.
+
+</Admonition>
+
+For Authorization we do insert a message and try to read it and then we it back as way to verify that the RLS policies set by the user are being respected by the user joining the channel but this messages won't be sent to the user. You can read more about it in the [Authorization](/docs/guides/realtime/authorization) docs
+
 ## Subscribe to messages
 
 You can use the Supabase client libraries to receive Broadcast messages.
@@ -384,6 +405,7 @@ You can use the Supabase client libraries to send Broadcast messages.
   </$Show>
 </Tabs>
 {/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}
+
 ### Broadcast from the Database
 
 <Admonition type="caution">
@@ -411,6 +433,14 @@ select
   );
 ```
 
+<Admonition type="note">
+
+The realtime.send function in the database includes a flag that determines whether the broadcast is private or public, and client channels also have the same configuration. For broadcasts to work correctly, these settings must match a public broadcast will only reach public channels, and a private broadcast will only reach private ones.
+
+By default, all database broadcasts are private, meaning clients must authenticate to receive them. If the database sends a public message but the client subscribes to a private channel, the message won't be delivered since private channels only accept signed, authenticated messages.
+
+</Admonition>
+
 It's a common use case to broadcast messages when a record is created, updated, or deleted. We provide a helper function specific to this use case, `realtime.broadcast_changes()`. For more details, check out the [Subscribing to Database Changes](/docs/guides/realtime/subscribing-to-database-changes) guide.
 
 ### Broadcast using the REST API