Skip to content

SHOUTBOX.md

Latest commit

 

History

History
385 lines (289 loc) · 7.63 KB

SHOUTBOX.md

File metadata and controls

385 lines (289 loc) · 7.63 KB

Global Shoutbox Documentation

Overview

The Shoutbox is a global, real-time, ephemeral message channel for DevTerm Network. Think of it as a digital hallway where developers can shout quick messages, share thoughts, or just say hi. Messages are not persisted to the database and exist only in memory.

Features

  • Real-time: Instant WebSocket broadcasting to all connected users
  • Ephemeral: No database storage, messages live in memory only
  • Global: Visible to everyone on the platform
  • Casual: No karma, no pressure, just quick shouts
  • Limited: 140 characters max (Twitter-style)
  • Simple: Three commands: shout, view, clear

Commands

Shout a Message

shout "<message>"

Broadcasts a message to the global shoutbox.

Constraints:

  • Maximum 140 characters
  • No karma awarded
  • Visible to all users immediately

Examples:

shout "Just deployed to production! 🚀"
shout "Anyone working on React hooks?"
shout "Coffee break time ☕"
shout "TIL: JavaScript has a flatMap() method"

Output:

📢 Shouted to the world!

"Just deployed to production! 🚀"

Use 'shoutbox view' to see recent shouts.

View Shoutbox

shoutbox view

Displays recent shouts from the global channel.

Output:

📢 Shoutbox (15 recent shouts)

[10:30:45] alice: Just deployed to production! 🚀
[10:31:12] bob: Anyone working on React hooks?
[10:32:03] charlie: Coffee break time ☕
[10:33:21] dave: TIL: JavaScript has a flatMap() method
[10:34:56] eve: Debug session going well!

Use 'shout "<message>"' to add yours!

Clear Shoutbox

shoutbox clear

Clears all messages from the shoutbox (future: admin only).

Output:

✅ Shoutbox cleared!

Use Cases

Quick Updates

shout "Pushing a hotfix, might be some downtime"
shout "Server back up!"

Ask Questions

shout "Anyone know a good Redis GUI?"
shout "What's your favorite VS Code theme?"

Share Wins

shout "Finally fixed that bug! 🎉"
shout "Shipped my first feature!"

Social Interaction

shout "Good morning devs! ☀️"
shout "Heading out, see you tomorrow!"

Share Learning

shout "TIL: CSS has a :has() selector now"
shout "Just discovered the nullish coalescing operator"

Technical Details

In-Memory Storage

Messages are stored in a simple array:

class ShoutboxService {
  constructor(io) {
    this.messages = [];
    this.MAX_MESSAGES = 100;
    this.MAX_CHAR_LIMIT = 140;
  }
}

Storage Details:

  • Maximum 100 messages kept in memory
  • Oldest messages removed when limit reached
  • All messages lost on server restart
  • No database persistence

Message Structure

{
  id: "1707424800000",
  username: "alice",
  userId: "user123",
  message: "Just deployed to production! 🚀",
  timestamp: "2026-02-08T18:00:00.000Z"
}

WebSocket Events

Client → Server:

// Send a shout
socket.emit('shoutbox:send', {
  user: { id: 'user123', username: 'alice' },
  message: 'Hello world!'
});

// Request shouts
socket.emit('shoutbox:get');

Server → Client:

// New shout broadcast
socket.on('shoutbox:message', (shout) => {
  console.log(`${shout.username}: ${shout.message}`);
});

// Shouts response
socket.on('shoutbox:messages', (shouts) => {
  console.log(`Received ${shouts.length} shouts`);
});

// Shoutbox cleared
socket.on('shoutbox:cleared', () => {
  console.log('Shoutbox was cleared');
});

// Error
socket.on('shoutbox:error', (data) => {
  console.error(data.error);
});

Character Limit

140 characters enforced on both client and server:

if (message.length > 140) {
  throw new Error('Message too long (max 140 characters)');
}

Why 140?

  • Forces concise communication
  • Twitter-inspired brevity
  • Prevents spam/abuse
  • Keeps shoutbox readable

Real-Time Flow

  1. User types: shout "Hello!"
  2. Client validates: Check 140 char limit
  3. WebSocket send: Emit to server
  4. Server validates: Re-check limit
  5. Server stores: Add to in-memory array
  6. Server broadcasts: Emit to all connected clients
  7. All clients receive: Display new shout

Comparison with Other Features

Feature Persistence Karma Visibility Purpose
Posts Database Yes Feed-based Permanent content
Comments Database Yes Post-specific Discussions
Collab Rooms Ephemeral No Room members Team chat
Shoutbox Ephemeral No Global Quick shouts

Best Practices

Good Shouts ✅

shout "Deploying v2.0 now"
shout "Anyone free for code review?"
shout "Found a great article on async/await"
shout "Happy Friday! 🎉"

Avoid ❌

# Too long
shout "I've been working on this really complex feature that involves refactoring the entire authentication system and I'm not sure if I should use JWT or sessions..."

# Spam
shout "Check out my blog!"
shout "Check out my blog!"
shout "Check out my blog!"

# Inappropriate
shout "This platform sucks"

Privacy & Moderation

No Persistence

  • Messages not saved to database
  • Lost on server restart
  • No edit history
  • No deletion needed (ephemeral)

No Karma

  • Encourages casual communication
  • No reputation impact
  • Low-pressure environment
  • Just for fun

Future Moderation

  • Rate limiting (e.g., 1 shout per minute)
  • Profanity filter
  • Admin clear capability
  • User mute/block

Examples

Morning Standup

shout "Starting work on the new dashboard"
shout "Fixing bugs from yesterday's deploy"
shout "Code review day for me!"

Deployment Updates

shout "Deploying to staging in 5 min"
shout "Staging deploy complete ✅"
shout "Testing on staging now"
shout "Looks good, deploying to prod"
shout "Production deploy successful! 🚀"

Learning & Sharing

shout "TIL: Array.prototype.at() exists"
shout "Great talk on microservices: [link]"
shout "Anyone tried Bun yet?"

Social

shout "Good morning everyone! ☀️"
shout "Lunch break 🍕"
shout "End of day, see you tomorrow!"

Limitations

By Design

  • No persistence: Messages lost on restart
  • No karma: Casual, low-stakes
  • No threading: Flat message list
  • No @mentions: Global broadcast only
  • No DMs: Public only

Technical

  • 100 message limit: Oldest removed
  • 140 char limit: Enforced strictly
  • In-memory only: RAM-based storage
  • No search: View recent only

Future Enhancements

  • Rate limiting: Prevent spam (1/min)
  • Profanity filter: Auto-moderate
  • Emoji reactions: Quick responses
  • User mentions: @username notifications
  • Hashtags: #topic filtering
  • Persistence option: Optional DB storage
  • Admin controls: Clear, mute, ban
  • Analytics: Popular times, active users

Troubleshooting

Message Not Appearing

Check WebSocket connection:

// In browser console
socket.connected // Should be true

Reconnect:

# Refresh page or
# Disconnect and reconnect socket

Character Limit Error

❌ Message too long (156/140 chars)

Solution: Shorten your message

# Too long
shout "I just finished implementing this really cool feature..."

# Better
shout "Just shipped a cool feature! 🎉"

Shoutbox Empty

No shouts yet. Be the first!

Solution: Be the first to shout!

shout "Hello world!"

Keep It Casual! 📢

The shoutbox is your digital hallway. Use it for:

  • Quick updates
  • Casual questions
  • Sharing wins
  • Saying hi

Type shout "Hello!" to get started!