streamflow/docs/PROJECT_STRUCTURE.md

StreamFlow IPTV - Project Structure

tv/
├── 📄 README.md                    # Main documentation
├── 📄 SETUP.md                     # Installation guide
├── 📄 ARCHITECTURE.md              # Architecture overview
├── 📄 package.json                 # Root package file
├── 📄 .env.example                 # Environment template
├── 📄 .gitignore                   # Git ignore rules
├── 📄 .dockerignore                # Docker ignore rules
├── 🐳 Dockerfile                   # Multi-stage Docker build
├── 🐳 docker-compose.yml           # Docker Compose config
├── 🚀 start.sh                     # Start script
├── 🛑 stop.sh                      # Stop script
│
├── 📁 backend/                     # Node.js Backend
│   ├── 📄 package.json            # Backend dependencies
│   ├── 🚀 server.js               # Main server file
│   ├── 💊 healthcheck.js          # Docker health check
│   │
│   ├── 📁 database/               # Database layer
│   │   └── 🗄️ db.js              # SQLite setup & schema
│   │
│   ├── 📁 middleware/             # Express middleware
│   │   └── 🔒 auth.js             # JWT authentication
│   │
│   ├── 📁 routes/                 # API endpoints
│   │   ├── 🔐 auth.js             # Authentication routes
│   │   ├── 📺 channels.js         # Channel management
│   │   ├── 📋 playlists.js        # Playlist management
│   │   ├── 📅 epg.js              # EPG data
│   │   ├── ⏺️ recordings.js       # Recording system
│   │   ├── 👤 profiles.js         # User profiles
│   │   ├── 📻 radio.js            # Radio channels
│   │   ├── 📂 groups.js           # Custom groups
│   │   ├── ⚙️ settings.js         # User settings
│   │   ├── 🎬 stream.js           # Stream proxy
│   │   └── 📊 stats.js            # Analytics
│   │
│   ├── 📁 jobs/                   # Background jobs
│   │   ├── 📡 epgSync.js          # EPG synchronization
│   │   ├── 💚 channelHealth.js    # Health monitoring
│   │   └── ⏰ recordingScheduler.js # Recording scheduler
│   │
│   └── 📁 utils/                  # Utilities
│       ├── 📝 logger.js           # Winston logger
│       └── 🔍 m3uParser.js        # M3U parser
│
├── 📁 frontend/                   # React Frontend
│   ├── 📄 package.json            # Frontend dependencies
│   ├── ⚙️ vite.config.js          # Vite configuration
│   ├── 📄 index.html              # HTML template
│   │
│   ├── 📁 public/                 # Static assets
│   │   ├── placeholder-channel.png
│   │   └── placeholder-show.png
│   │
│   └── 📁 src/                    # Source code
│       ├── 🎯 main.jsx            # Entry point
│       ├── 🎨 App.jsx             # Main app component
│       ├── 🌍 i18n.js             # Internationalization
│       ├── 🎨 theme.js            # MUI themes
│       ├── 💅 index.css           # Global styles
│       │
│       ├── 📁 components/         # React components
│       │   ├── 🎬 VideoPlayer.jsx # Video player
│       │   ├── 📺 EPGTimeline.jsx # EPG viewer
│       │   ├── 🏠 Sidebar.jsx     # Navigation sidebar
│       │   └── 🔝 Header.jsx      # Top header
│       │
│       ├── 📁 pages/              # Page components
│       │   ├── 🔐 Login.jsx       # Login page
│       │   ├── 📝 Register.jsx    # Registration page
│       │   ├── 📊 Dashboard.jsx   # Main dashboard
│       │   ├── 📺 LiveTV.jsx      # Live TV page
│       │   ├── 📻 Radio.jsx       # Radio page
│       │   ├── 🎬 Movies.jsx      # Movies page
│       │   ├── 📺 Series.jsx      # Series page
│       │   ├── ⭐ Favorites.jsx   # Favorites page
│       │   └── ⚙️ Settings.jsx    # Settings page
│       │
│       ├── 📁 store/              # Zustand stores
│       │   ├── 🔐 authStore.js    # Auth state
│       │   └── 🎨 themeStore.js   # Theme state
│       │
│       ├── 📁 utils/              # Utilities
│       │   └── 🌐 api.js          # Axios client
│       │
│       └── 📁 locales/            # Translations
│           ├── 🇬🇧 en.json        # English
│           └── 🇷🇴 ro.json        # Romanian
│
├── 📁 data/                       # Persistent data (Docker volume)
│   ├── 📁 playlists/             # Uploaded playlists
│   ├── 📁 recordings/            # Recorded content
│   ├── 📁 logos/                 # Channel logos
│   ├── 📁 epg/                   # EPG cache
│   ├── 📁 uploads/               # User uploads
│   └── 🗄️ streamflow.db         # SQLite database
│
└── 📁 logs/                       # Application logs (Docker volume)
    ├── 📄 error.log              # Error logs
    └── 📄 combined.log           # All logs

File Count Summary

• Total Files: 52
• Backend Files: 17
• Frontend Files: 25
• Configuration: 7
• Documentation: 3

Key Technologies by Layer

Backend

• Runtime: Node.js 20 (Alpine Linux)
• Framework: Express.js
• Database: SQLite3
• Authentication: JWT + Bcrypt
• Security: Helmet, CORS, Rate Limiting
• Media: FFmpeg, Streamlink
• Jobs: node-cron
• Logging: Winston

Frontend

• Framework: React 18
• Build Tool: Vite
• UI Library: Material-UI (MUI) 5
• Router: React Router 6
• State: Zustand
• HTTP Client: Axios
• i18n: i18next
• Video: React Player

Infrastructure

• Container: Docker (Alpine base)
• Orchestration: Docker Compose
• Volumes: Named volumes for data/logs
• Network: Bridge network
• Health: Automatic health checks

Lines of Code (Approximate)

Component	Lines
Backend Routes	~800
Database Schema	~200
Frontend Components	~1200
Pages	~800
Configuration	~400
Total	~3400

Security Features by File

File	Security Features
Dockerfile	Non-root user, capability dropping, minimal base
docker-compose.yml	Security opts, resource limits, health checks
backend/middleware/auth.js	JWT validation, role-based access
backend/routes/auth.js	Bcrypt hashing, rate limiting, input validation
backend/server.js	Helmet headers, CORS, compression
frontend/src/utils/api.js	Token injection, 401 handling

Development Workflow

1. 📝 Edit source files
   └── backend/ or frontend/src/

2. 🔧 Test locally
   └── npm run dev:backend
   └── npm run dev:frontend

3. 🏗️ Build Docker image
   └── docker-compose build

4. 🚀 Deploy container
   └── docker-compose up -d

5. ✅ Verify deployment
   └── http://localhost:12345

Production Checklist

• Change JWT_SECRET in .env
• Change SESSION_SECRET in .env
• Set NODE_ENV=production
• Configure SSL/HTTPS (reverse proxy)
• Set up firewall rules
• Configure backup schedule
• Set up monitoring/alerts
• Test all features
• Review logs for errors
• Document custom configurations

---

Last Updated: December 2025
Version: 1.0.0