Seen

A modern self-hosted media control center for movies, TV shows, and games. Built with Go, SolidJS, PostgreSQL, and Dragonfly.

🎯 Features

• Unified Media Tracking: Movies, TV shows, and games in one place
• Smart Discovery: Browse trending, popular, and top-rated content
• Watch Later / Backlog: Organize your media queue
• Progress Tracking: Resume where you left off
• Download Management: Track and manage downloads with state machine
• Beautiful UI: Brutalist cinema design with dark/light themes
• Fast Performance: Dragonfly cache for 20-40x speed improvements
• Self-Hosted: Full control over your data

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• 2GB+ RAM
• 10GB+ disk space

Development Setup

# Clone the repository
git clone <repository-url>
cd seen

# Copy environment files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# Start all services
docker compose up -d

# Access the application
# Frontend: http://localhost:8080
# Backend API: http://localhost:8081

Production Deployment

See DEPLOYMENT_GUIDE.md for detailed production setup instructions.

Quick production start:

# Generate secrets
./scripts/generate-secrets.sh

# Configure production environment
cp backend/.env.production backend/.env.production.local
# Edit .env.production.local with your secrets

# Deploy with production config
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

📚 Documentation

• Deployment Guide - Production deployment instructions
• Security Policy - Security best practices and guidelines
• Production Readiness Report - Assessment and checklist
• Backend Documentation - API reference
• Frontend Design - Design system documentation

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Frontend (SolidJS)                    │
│  Modern brutalist UI with responsive design              │
└─────────────────────┬───────────────────────────────────┘
                      │ HTTP/REST
┌─────────────────────▼───────────────────────────────────┐
│                    Backend (Go + Gin)                    │
│  Authentication, Catalog, Downloads, Progress            │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
┌───────▼──────┐ ┌───▼────┐ ┌─────▼────────┐
│  PostgreSQL  │ │Dragonfly│ │ TMDB / IGDB  │
│   Database   │ │  Cache  │ │   APIs       │
└──────────────┘ └─────────┘ └──────────────┘

🛠️ Technology Stack

Backend

• Language: Go 1.25
• Framework: Gin
• Database: PostgreSQL 16
• Cache: Dragonfly (Redis-compatible)
• Auth: JWT with bcrypt
• Migrations: Goose
• Query Builder: sqlc

Frontend

• Framework: SolidJS
• Language: TypeScript
• Build Tool: Vite
• Styling: TailwindCSS
• Testing: Vitest + Playwright
• Server: Nginx

Infrastructure

• Containerization: Docker
• Orchestration: Docker Compose
• Reverse Proxy: Nginx
• SSL/TLS: Let's Encrypt (recommended)

📊 Current Status

• ✅ Backend: Fully functional with all core features
• ✅ Frontend: Complete UI with brutalist cinema design
• ✅ Authentication: JWT-based auth with sessions
• ✅ Catalog: Movies, TV, games with TMDB/IGDB integration
• ✅ Downloads: State machine with progress tracking
• ✅ Cache: Dragonfly integration for performance
• ✅ Docker: Production-ready deployment
• ⚠️ Production: Requires security configuration (see checklist)

🔒 Security

Before deploying to production:

1. Generate strong secrets: ./scripts/generate-secrets.sh
2. Configure HTTPS/TLS with Let's Encrypt
3. Update CORS settings for your domain
4. Enable rate limiting
5. Set up automated backups

See SECURITY.md for complete security guidelines.

🧪 Testing

# Backend tests
cd backend
go test ./...

# Frontend unit tests
cd frontend
npm run test:unit

# Frontend E2E tests
npm run test:e2e

# API integration tests
cd backend
./test-api.sh

📦 API Endpoints

Authentication

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User login
• POST /api/v1/auth/refresh - Token refresh
• GET /api/v1/auth/me - Current user

Catalog

• GET /api/v1/dashboard - Dashboard data
• GET /api/v1/discover - Browse content
• GET /api/v1/search - Search media
• GET /api/v1/games - Game catalog

Watch Later

• GET /api/v1/watch-later - Get list
• POST /api/v1/watch-later - Add item
• DELETE /api/v1/watch-later/:id - Remove item

Progress

• GET /api/v1/progress/continue-watching - Continue watching
• POST /api/v1/progress - Update progress

Downloads

• POST /api/v1/downloads - Create download
• GET /api/v1/downloads - List downloads
• DELETE /api/v1/downloads/:id - Cancel download
• GET /api/v1/downloads/:id/events - Download events

🔧 Configuration

Backend Environment Variables

Key variables (see backend/.env.production for full list):

SEEN_ENV=production
SEEN_HTTP_PORT=8081
SEEN_POSTGRES_URL=postgres://user:pass@host:5432/seen
SEEN_CACHE_ADDR=dragonfly:6379
SEEN_AUTH_JWT_SECRET=<strong-secret>
SEEN_TMDB_API_KEY=<your-key>
SEEN_IGDB_CLIENT_ID=<your-id>
SEEN_IGDB_CLIENT_SECRET=<your-secret>

Frontend Environment Variables

VITE_APP_NAME=Seen
VITE_ENABLE_MOCK_API=false
VITE_API_BASE_URL=

🔄 Backup and Restore

Automated Backups

Backups run daily when using production compose file:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Manual Backup

docker exec seen-postgres pg_dump -U seen seen | gzip > backup.sql.gz

Restore

docker exec -i seen-backup /restore.sh /backups/backup.sql.gz

📈 Performance

• Response Times: <50ms for cached endpoints
• Cache Hit Rate: 80-90% for catalog queries
• Database: Connection pooling with 25 max connections
• Memory: ~1.5GB total for all services
• CPU: Optimized for multi-core systems

🗺️ Roadmap

Phase 2 (Current)

• ✅ Download management
• ✅ Progress tracking
• ✅ Watch later lists
• ✅ Dragonfly cache integration

Phase 3 (Planned)

• Media library scanning
• File metadata extraction
• Subtitle management
• Recommendation engine
• Release calendar
• Collections

Phase 4 (Future)

• Built-in media player
• WebSocket real-time updates
• Multi-user support
• Mobile app
• Plex integration
• Torrent client integration

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📝 License

See LICENSE file for details.

🙏 Acknowledgments

• TMDB - Movie and TV metadata
• IGDB - Game metadata
• Dragonfly - High-performance cache
• SolidJS - Reactive UI framework
• Gin - Go web framework

📧 Support

For issues and questions:

• GitHub Issues: Report bugs and request features
• Documentation: Check the docs folder
• Security: See SECURITY.md for vulnerability reporting

---

Status: Production Ready (with security configuration)
Version: 0.1.0
Last Updated: April 6, 2026