# ishwanku/rtsp-stream-viewer architecture

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

- Interactive diagram: https://gitdiagram.com/ishwanku/rtsp-stream-viewer
- Repository: https://github.com/ishwanku/rtsp-stream-viewer

## Overview

##### Project type and purpose
- This is a full-stack web application (“RTSP Stream Viewer”) whose goal is to let users view live RTSP camera feeds in the browser.
- Frontend: React (Vite, Tailwind CSS), deployed on Vercel.
- Backend: Django + Django Channels (ASGI), FFmpeg for stream transcoding, Redis for channel layer, deployed on Vercel.

##### File structure
- Top-level “frontend” directory contains a React project (Vite config, package.json, tailwind, components under src/ components).
- Top-level “backend” directory contains a Django project (manage.py, requirements.txt, asgi.py and wsgi.py, apps under backend/stream).
- “stream” app uses consumers.py (WebSocket consumers), models.py, views.py.
- Configuration files: backend/vercel.json, front- end/vercel.json for deployment; backend/build.sh; Redis URL set via environment variables.

##### README for additional insights
- The README clarifies use of FFmpeg to pull RTSP and push frames to Channels group.
- Environment variables: SECRET_KEY, DEBUG, REDIS_URL.
- Local dev instructions for both front and back; mentions Upstash Redis.

##### Relationships & data flow
1. User loads React app from Vercel.
2. User submits RTSP URL → React sends HTTP POST to Django REST endpoint.
3. Django view triggers an FFmpeg process to pull RTSP, convert to frames or HLS/chunks, and publish into a Channels group via Redis.
4. React opens a WebSocket to the Django Channels endpoint (ASGI).
5. Django Channels consumer reads processed frames from the group (via Redis) and pushes them over the open WebSocket.
6. React StreamPlayer receives binary/frame data and renders video.

##### Architectural patterns & design principles
- Separation of concerns: UI (React) / API & real-time (Django Channels)
- Event-driven real-time streaming via WebSockets and channel layer (Redis)
- Micro-pub/sub pattern: FFmpeg acts as publisher, Django Channels as dispatcher, React as subscriber.
- Stateless frontend; backend uses ephemeral subprocesses for FFmpeg and Redis for stateful pub/sub.

##### Technologies & frameworks to label
- React, Vite, Tailwind CSS (frontend)
- Django, Django Channels, Redis (backend)
- FFmpeg (stream processing)
- Vercel (deployment)
- Upstash or cloud Redis (channel layer)

##### Elements
- Labels for each component (e.g., “React UI,” “Django ASGI,” “FFmpeg Process,” “Redis Channel Layer”).
– RTSP camera → FFmpeg
– FFmpeg → Redis
– React HTTP → Django REST
– React WS ↔ Django Channels
– Browser render path
– Blue for frontend components
– Green for backend services
– Orange for external systems (RTSP, Redis)

##### Final advice
– Be as granular as necessary: each subprocess (FFmpeg), each protocol (HTTP vs WS), each service (Redis).
– Emphasize the real-time streaming path (camera → FFmpeg → Redis → WebSocket → browser).
– Review routes in backend/rtsp_viewer/routing.py and stream/consumers.py to ensure all endpoints and channel groups are represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Vercel Deployment"
        subgraph "Frontend (React)" 
            direction TB
            App["App.jsx"]:::frontend
            main["main.jsx"]:::frontend
            AddForm["AddStreamForm.jsx"]:::frontend
            StreamInput["StreamInput.jsx"]:::frontend
            StreamPlayer["StreamPlayer.jsx"]:::frontend
            HTTPClient["HTTP Client (fetch API)"]:::frontend
            WSClient["WebSocket Client"]:::frontend
            Vite["vite.config.js"]:::frontend
            Tailwind["tailwind.config.js"]:::frontend
            Package["package.json"]:::frontend
            VercelFront["vercel.json"]:::frontend
        end

        subgraph "Backend (Django)" 
            direction TB
            manage["manage.py"]:::backend
            requirements["requirements.txt"]:::backend
            BuildSh["build.sh"]:::backend
            VercelBack["vercel.json"]:::backend
            Settings["settings.py"]:::backend
            subgraph "HTTP REST API"
                ViewsGlobal["rtsp_viewer/views.py"]:::backend
                StreamViews["stream/views.py"]:::backend
                StreamURLs["stream/urls.py"]:::backend
                GlobalURLs["rtsp_viewer/urls.py"]:::backend
            end
            subgraph "ASGI / WebSocket"
                ASGI["asgi.py"]:::backend
                Routing["routing.py"]:::backend
                Consumers["consumers.py"]:::backend
            end
            Models["models.py"]:::backend
            Migrations["migrations/__init__.py"]:::backend
            FFmpeg["FFmpeg Process"]:::backend
        end
    end

    subgraph External
        RTSP["RTSP Camera"]:::external
        Redis["Redis Channel Layer"]:::external
    end

    Browser["Browser"]:::frontend

    Browser -->|loads app| App
    App -->|HTTP POST /register| HTTPClient
    HTTPClient -->|calls REST| StreamViews
    StreamViews -->|invokes| FFmpeg
    RTSP -->|pull stream| FFmpeg
    FFmpeg -->|publish frames| Redis
    ASGI -->|subscribe| Redis
    Browser -->|opens WS| WSClient
    WSClient -->|connects WS| ASGI
    ASGI -->|sends frames| WSClient
    WSClient -->|renders| StreamPlayer

    classDef frontend fill:#D0E8FF,stroke:#0057D9,color:#003366;
    classDef backend fill:#E0F4E0,stroke:#2E7D32,color:#1B5E20;
    classDef external fill:#FFEFD5,stroke:#FFA500,color:#FF8C00;

    click AddForm "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/src/components/AddStreamForm.jsx"
    click StreamInput "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/src/components/StreamInput.jsx"
    click StreamPlayer "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/src/components/StreamPlayer.jsx"
    click App "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/src/App.jsx"
    click main "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/src/main.jsx"
    click Vite "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/vite.config.js"
    click Tailwind "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/tailwind.config.js"
    click Package "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/package.json"
    click VercelFront "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/frontend/vercel.json"
    click ViewsGlobal "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/rtsp_viewer/views.py"
    click StreamViews "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/stream/views.py"
    click StreamURLs "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/stream/urls.py"
    click GlobalURLs "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/rtsp_viewer/urls.py"
    click ASGI "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/rtsp_viewer/asgi.py"
    click Routing "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/rtsp_viewer/routing.py"
    click Consumers "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/stream/consumers.py"
    click Models "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/stream/models.py"
    click Migrations "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/stream/migrations/__init__.py"
    click manage "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/manage.py"
    click requirements "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/requirements.txt"
    click BuildSh "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/build.sh"
    click VercelBack "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/vercel.json"
    click Settings "https://github.com/ishwanku/rtsp-stream-viewer/blob/main/backend/rtsp_viewer/settings.py"
```
