🎙️ Podcastic

A modern, ultra-responsive multi-user podcast streaming application with an Apple TV-inspired design.

✨ Features

• Podcast Discovery & Management: Search, subscribe, and organize your favorite podcasts
• Stream Playback: Direct audio streaming without disk usage
• Dashboard: View latest episodes from all subscriptions
• User Accounts: Multi-user with JWT authentication
• Responsive Design: Mobile-first, works perfectly on all devices
• Ultra-Fast: Optimized with Redis caching and efficient database queries
• Docker Ready: Containerized for easy deployment

🛠️ Tech Stack

Frontend

• React 18 + TypeScript
• Vite (ultra-fast bundler)
• Tailwind CSS (styling with Apple TV aesthetic)
• React Router (navigation)
• TanStack Query (server state management)

Backend

• Node.js + Express.js
• MongoDB (flexible data storage)
• Redis (caching & performance)
• JWT (authentication)
• TypeScript

DevOps

• Docker & Docker Compose
• Alpine images for minimal size

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (recommended)
• Node.js 20+ (for local development)
• MongoDB (local or Atlas)
• Redis (local or cloud)

Using Docker Compose (Recommended)

# Clone and enter directory
cd Podcastic

# Create .env file from template
cp .env.example .env

# Start all services
docker-compose up -d

# Frontend: http://localhost:3000
# Backend API: http://localhost:5000
# MongoDB: localhost:27017
# Redis: localhost:6379

Local Development

Backend

cd backend
npm install
npm run dev  # Starts on port 5000

Frontend

cd frontend
npm install
npm run dev  # Starts on port 3000

📁 Project Structure

Podcastic/
├── frontend/          # React + Vite application
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── styles/
│   └── Dockerfile
│
├── backend/           # Express.js API
│   ├── src/
│   │   ├── routes/
│   │   ├── controllers/
│   │   ├── models/
│   │   ├── middleware/
│   │   ├── services/
│   │   └── config/
│   └── Dockerfile
│
├── docker-compose.yml
├── .env.example
└── README.md

🔑 Key Models

User

• Email, password, username, avatar
• Preferences (playback speed, theme, language)

Podcast

• Title, description, RSS URL, image
• Author, categories, language
• Episode count, last fetched timestamp

Episode

• Title, description, audio URL
• Publication date, duration
• Unique GUID per podcast

UserProgress

• Current position in episode (seconds)
• Completion status
• Saved episodes
• Listen history

📡 API Endpoints (To be implemented)

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/refresh - Refresh access token

Podcasts

• GET /api/podcasts - Get user subscriptions
• POST /api/podcasts/subscribe - Add subscription
• DELETE /api/podcasts/:id/unsubscribe - Remove subscription
• GET /api/podcasts/search - Search podcasts

Episodes

• GET /api/episodes/latest - Latest episodes dashboard
• GET /api/episodes/:id - Get episode details
• GET /api/podcasts/:id/episodes - Podcast episodes

Progress

• POST /api/progress - Save listening position
• GET /api/progress/:episodeId - Get saved position

🎨 Design System

Apple TV Style

• Light theme with subtle gradients
• Glassmorphism effects (backdrop blur)
• Rounded corners (lg/xl)
• Soft shadows for depth
• Generous spacing

Responsive Breakpoints

• Mobile: < 640px
• Tablet: 640px - 1024px
• Desktop: 1024px+

🔒 Security

• JWT tokens for stateless authentication
• Bcrypt password hashing
• CORS configured
• Input validation with Zod
• Environment variables for secrets

📊 Performance Targets

• Dashboard load: < 1s (on 4G)
• Stream start: < 2s
• Docker image: < 100MB total
• Startup time: < 5s

🐳 Docker Commands

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f [service_name]

# Rebuild images
docker-compose build --no-cache

# Remove volumes (careful!)
docker-compose down -v

🧪 Testing

Coming soon...

📝 Development Workflow

1. Create feature branch: git checkout -b feature/my-feature
2. Make changes
3. Test thoroughly
4. Commit: git commit -m "feat: add my feature"
5. Push: git push origin feature/my-feature

🔄 Environment Variables

See .env.example for all available options. Key ones:

• NODE_ENV - development/production
• MONGODB_URI - MongoDB connection string
• REDIS_URL - Redis connection URL
• JWT_SECRET - Secret for signing tokens
• PODCAST_INDEX_API_KEY - API key for podcast search (optional)

📚 Resources

• React Documentation
• Express.js Guide
• MongoDB Docs
• Tailwind CSS
• TypeScript Handbook

📄 License

MIT

👨‍💻 Author

Built with ❤️

---

Status: Under development - Phase 1 (Foundation) in progress