# fanout/django-eventstream architecture

> Architecture diagram of the GitHub repository fanout/django-eventstream, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fanout/django-eventstream
- Repository: https://github.com/fanout/django-eventstream

## Overview

##### Project type and purpose
- This is a reusable Django library (django-eventstream) that adds Server-Sent Events (SSE) support to any Django project.
- It exposes Django views and DRF viewsets to stream real-time events over HTTP, with optional persistence (database) and scalability (Redis or GRIP proxy).

##### File structure
- Top-level module: django_eventstream/
- channelmanager.py – authorization hooks for per-user channels
- event*.py & eventstream.py – core request/response and stream handling
- storage.py & migrations – optional DB persistence of events
- renderers/ – SSE and browsable-API renderers for DRF integration
- static/ + templates/ – client-side JS/CSS for browsers
- views.py, viewsets.py – Django and DRF endpoints
- management/commands – utilities, e.g. runserver_ngrok
- examples/ – three sample Django projects demonstrating basic usage, DRF integration, and templating
- tests/ – unit tests for storage and streaming

##### Extract additional insights from README
- Protocol: Clients connect with “Accept: text/event-stream” to long-running HTTP GET.
- send_event API publishes to channels.
- Scaling options:
- Single process (no storage): events lost on disconnect
- Database storage via DjangoModelStorage for reliable delivery
- Redis pub/sub or GRIP proxy (Pushpin/Fanout) for multi-instance architectures
- DRF integration: configurable EventsViewSet + custom SSE renderers

- Client layer
- Browser or native app with EventSource / ReconnectingEventSource libraries
- Ingress / Edge
- (Optional) Load Balancer or API Gateway
- (Optional) GRIP proxy (e.g., Pushpin) for connection offloading
- Application server
- ASGI server (Daphne) running Django + django_eventstream
- Django middleware stack (including GripMiddleware if used)
- URL router → SSE endpoints (django_eventstream.urls)
- DRF router → EventsViewSet (if DRF used)
- Event pipeline
- send_event() call → ChannelManager authorization → storage layer → publish to subscribers
- Storage & pub/sub
- Primary database (PostgreSQL/MySQL) for models & optional DjangoModelStorage
- Redis (optional) for cross-instance pub/sub
- External services
- GRIP proxy (Pushpin or Fastly Fanout)
- Redis server
- Upstream data sources (your app code that calls send_event)

b. Relationships & data flows
- Client GET → Load Balancer → (GRIP proxy) → Daphne
- Event request enters Django, passes through ChannelManager
- Long-running HTTP connection held open by Daphne/GRIP
- send_event in application code pushes event into storage or Redis
- Subscriber loop in django_eventstream fetches new events → SSE frames → client
- On multiple instances, Redis or GRIP proxy fan-out events across all backends

c. Architectural patterns & design principles
- Pub/Sub (channels)
- Event sourcing with optional persistent store
- Plug-in architecture: channel managers, storage backends, renderers
- ASGI for long-lived connections
- Integration with DRF via viewsets and renderers

d. Key technologies & frameworks
- Python, Django, ASGI, Daphne
- Django REST Framework (optional)
- Redis (optional)
- GRIP protocol / Pushpin (optional)
- PostgreSQL / MySQL / SQLite for event storage
- Browser EventSource / reconnecting-eventsource.js

##### Final advice
- Be exhaustive in listing the components the library provides and integrates with
- Both the control flow (authorization, routing) and data flow (event publish/subscribe)
- Extension points: custom ChannelManager, storage backends, renderer classes
- Iterate as you confirm which features (Redis, GRIP, DRF) are enabled in a given deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Browser["Browser EventSource\n(reconnecting-eventsource.js)"]:::client
        NativeApp["Native App\n(EventSource)"]:::client
    end

    %% Edge / Network Layer
    subgraph "Network / Edge" 
        direction TB
        LoadBalancer["Load Balancer / API Gateway"]:::edge
        GRIPProxy["GRIP Proxy\n(Pushpin / Fanout)"]:::edge
    end

    %% Application Layer
    subgraph "Application Server" 
        direction TB
        Daphne["Daphne ASGI Server"]:::app
        Middleware["Django Middleware\n(including GripMiddleware)"]:::app
        Router["URL Router\n(django_eventstream.urls)"]:::app
        SSEEndpoint["SSE Endpoint\nviews.py / viewsets.py"]:::app
        ChannelManager["ChannelManager"]:::app
        EventHandling["Core Event Handling"]:::app
        DRFRenderers["DRF Renderers"]:::app
        ManagementCmds["Management Commands"]:::app
    end

    %% Storage / PubSub Layer
    subgraph "Storage & Pub/Sub" 
        direction TB
        DB[(Database)]:::storage
        Redis["Redis Pub/Sub"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        UpstreamApp["Your App Code\n(send_event API)"]:::external
    end

    %% Clients to Edge
    Browser -->|"HTTP GET /events/ (Accept: text/event-stream)"| LoadBalancer
    NativeApp -->|"HTTP GET /events/"| LoadBalancer

    %% Edge to App
    LoadBalancer -->|"Forward request"| GRIPProxy
    GRIPProxy -->|"GRIP long-lived HTTP"| Daphne

    %% Request flow in App
    Daphne -->|"ASGI request"| Middleware
    Middleware -->|"URL resolution"| Router
    Router -->|"route to SSE"| SSEEndpoint
    SSEEndpoint -->|"authorize channel"| ChannelManager
    SSEEndpoint -->|"handle stream"| EventHandling

    %% Publish flow
    UpstreamApp -->|"send_event()"| ChannelManager
    ChannelManager -->|"store or publish"| DB
    ChannelManager -->|"publish"| Redis
    Redis -->|"fan-out"| Daphne

    %% Event dispatch to client
    EventHandling -->|"poll/push"| DB
    EventHandling -->|"subscribe"| Redis
    EventHandling -->|"SSE frames"| GRIPProxy
    GRIPProxy -->|"deliver frames"| Browser
    GRIPProxy -->|"deliver frames"| NativeApp

    %% Optional components dashed
    class DB,Redis dashed

    %% Click Events
    click ChannelManager "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/channelmanager.py"
    click EventHandling "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/event.py"
    click EventHandling "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/eventrequest.py"
    click EventHandling "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/eventresponse.py"
    click EventHandling "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/eventstream.py"
    click DB "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/storage.py"
    click DB "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/models.py"
    click DB "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/migrations/0001_initial.py"
    click DRFRenderers "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/renderers/sserenderer.py"
    click DRFRenderers "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/renderers/browsableapieventstreamrenderer.py"
    click Browser "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/static/django_eventstream/js/reconnecting-eventsource.js"
    click Browser "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/static/django_eventstream/js/browsable-api-eventstream.js"
    click Browser "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/static/django_eventstream/css/browsable-api-eventstream.css"
    click Browser "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/static/django_eventstream/json2.js"
    click SSEEndpoint "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/views.py"
    click SSEEndpoint "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/viewsets.py"
    click Router "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/urls.py"
    click ManagementCmds "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/management/commands/runserver_ngrok.py"
    click Middleware "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/apps.py"
    click ManagementCmds "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/admin.py"
    click ManagementCmds "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/utils.py"
    click External "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/__init__.py"
    click External "https://github.com/fanout/django-eventstream/blob/master/django_eventstream/tests.py"
    click External "https://github.com/fanout/django-eventstream/blob/master/tests/test_storage.py"
    click External "https://github.com/fanout/django-eventstream/blob/master/tests/test_stream.py"

    %% Styles
    classDef client fill:#cce5ff,stroke:#005cbf,color:#004085
    classDef edge fill:#ffe5b4,stroke:#ff8800,color:#b36200
    classDef app fill:#d4edda,stroke:#28a745,color:#155724
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef external fill:#f8d7da,stroke:#dc3545,color:#721c24
    classDef dashed stroke-dasharray: 5 5;border-color:#6c757d
```
