docs: clarify project scope and enhance README documentation

[Copilot]

The README needed clearer positioning that fastpubsub is not a replacement for production message brokers like Pub/Sub, NATS, or Kafka, but rather brings pub/sub capabilities to PostgreSQL-based architectures.

Changes

Project Positioning

• Added "What is fastpubsub?" section explicitly stating this is not a replacement for dedicated message brokers
• Defined clear use cases: when PostgreSQL is already deployed and infrastructure simplicity is prioritized
• Outlined when to use dedicated brokers instead (high throughput, multi-datacenter, advanced routing)

Documentation Structure

• Moved Message Flow section earlier (after Architecture) for better comprehension before diving into usage
• Maintains logical progression: Overview → Architecture → Flow → Quick Start → API Reference → Examples

Enhanced Examples

Added 4 production-ready examples:

• Multiple Consumers: Parallel processing with unique consumer IDs
• Error Handling Pattern: Complete Python implementation distinguishing retriable vs permanent errors
• Monitoring & Alerting: Grafana/Prometheus setup with alert rules for DLQ and backlog
• Topic Fan-out: Single event to multiple filtered subscriptions

All Python examples include proper imports, exception definitions, and error handling patterns:

# Example 10 shows proper error categorization
class RetriableError(Exception):
    """Temporary error that should be retried"""
    pass

class PermanentError(Exception):
    """Permanent error that should not be retried"""
    pass

# ACK permanent errors to avoid infinite retries
# NACK retriable errors to trigger exponential backoff

Removed

• No benchmark mentions (none existed, confirmed clean)

Original prompt

Improve the content of the README.md file.

Some considerations:

• Make it clear that the objective of the project is not to replace services like GooglePubSub/Nats/Kafka, the main objective of the project is to offer certain features of these services to run on simple architectures where you have postgresql available.
• Rearrange documentation sections for better reading.
• Add more examples as you see fit.
• Don't mention anything related to benchmarks, because we don't have the data.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.