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