Pronunciation: a·pol·lon·ia
Apollonia is a comprehensive media catalog system that automatically detects, classifies, and analyzes audio and video files using machine learning. Built with a modern microservices architecture, it provides real-time processing, advanced analytics, and a responsive web interface for managing large media collections.
- Automatic Media Detection: Monitors directories and automatically processes new media files
- ML-Powered Analysis: Uses TensorFlow and Essentia for audio/video feature extraction
- Real-time Processing: Event-driven architecture with AMQP message queuing
- Comprehensive API: RESTful and GraphQL APIs with JWT authentication
- Modern Web Interface: React-based UI with real-time updates and analytics
- Scalable Architecture: Microservices design with Docker containerization
- Multi-format Support: Handles various audio (MP3, WAV, FLAC) and video (MP4, AVI, MOV) formats
- Backend: Python 3.12 | FastAPI | Strawberry GraphQL
- Frontend: React 18 | TypeScript | Vite | Tailwind CSS
- Machine Learning: TensorFlow | Essentia | Librosa
- Databases: PostgreSQL | Neo4j | Redis
- Message Queue: RabbitMQ | aio-pika
- Package Management: uv | npm
- Task Runner: Just | Taskipy
- Code Quality: Ruff | mypy | ESLint | Prettier
- Testing: pytest | Vitest | Testing Library
- Git Hooks: pre-commit
- Containerization: Docker | Docker Compose
- CI/CD: GitHub Actions
- Container Registry: GitHub Container Registry
- Monitoring: Prometheus | Grafana | Jaeger
- UI Components: Radix UI | Headless UI | Heroicons
- State Management: Zustand | TanStack Query
- Data Visualization: Recharts | Framer Motion
- Forms: React Hook Form | Zod
The system consists of several specialized services:
- Media Ingestor: Monitors directories and detects media files
- ML Analyzer: Extracts features using TensorFlow/Essentia models
- Database Populator: Stores metadata in PostgreSQL and Neo4j
- API Service: Provides REST and GraphQL endpoints
- Frontend: React-based web application
- Python 3.12 (for TensorFlow/Essentia compatibility)
- Docker and Docker Compose for containerized deployment
- PostgreSQL for primary data storage
- RabbitMQ for message queuing
- Redis for caching
- Neo4j for graph relationships (optional)
- Node.js 22+ for frontend development
- Docker and Docker Compose (v2.0+)
- Git
- 8GB RAM minimum (16GB recommended for ML features)
- 20GB free disk space
-
Clone the repository:
git clone https://github.com/SimplicityGuy/apollonia.git cd apollonia -
Start the services:
docker-compose up -d
This will start:
- PostgreSQL database
- RabbitMQ message broker
- Redis cache
- Neo4j graph database
- All microservices
- Frontend web application
-
Monitor the logs:
docker-compose logs -f
-
Access the web interface:
Open http://localhost:3000 in your browser
Default credentials:
- Username:
admin - Password:
admin123
- Username:
-
Add media files:
# Copy files to monitored directories cp your-music/* ./data/music/ cp your-videos/* ./data/videos/ # Or use the web interface upload feature
The system will automatically:
- Detect new files
- Extract metadata
- Analyze content using ML models
- Index for searching
- Generate thumbnails and previews
For detailed development instructions, see the Development Guide.
The project uses Just as a command runner for all development tasks.
# Install Just (if not already installed)
cargo install just
# Or on macOS
brew install just
# Set up development environment
just install
# Start all services
just up
# Run tests
just test
# Run quality checks
just check
# See all available commands
just --list# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync --all-extras
# Install pre-commit hooks
uv run task install-hooks
# Run quality checks
uv run task check- 🚀 Package Manager: uv - Ultra-fast Python package installer and resolver
- 🎯 Task Runner: Just - Command runner for development workflows
- 🧹 Code Formatter: Ruff - Extremely fast Python linter and formatter
- 🔍 Type Checker: mypy - Static type checker for Python
- 🧪 Testing: pytest for Python | Vitest for Frontend
- 🛡️ Security: Bandit | pip-audit | Trivy
- 🪝 Git Hooks: pre-commit - Multi-language pre-commit framework
- 📦 Containerization: Docker with multi-stage builds and health checks
-
Getting Started
- Quick Start Guide - Initial setup and usage
- Architecture Overview - System design and components
- API Documentation - REST and GraphQL reference
-
Development
- Development Guide - Setup and workflow instructions
- Python Version Notes - Python version strategy
- Frontend Development - React application guide
- Testing Guide - Unit, integration, and E2E tests
-
Services
- Media Ingestor - File monitoring service
- ML Analyzer - Machine learning analysis
- Database Populator - Data persistence service
- API Service - REST and GraphQL endpoints
-
Operations
- Docker Deployment - Container deployment guide
- Configuration - Environment variables and settings
- Performance Tuning - Optimization guide
- Monitoring - Metrics and observability
-
CI/CD
- GitHub Workflows - CI/CD pipeline documentation
- Composite Actions - Reusable workflow components
- Emoji Logging Convention - Standardized logging with emojis
- Justfile Commands - Development task runner reference
-
Contributing
- Contributing Guide - How to contribute
- Claude Code Guide - Instructions for AI-assisted development
This project is licensed under the MIT License - see the LICENSE file for details.
Robert Wlodarczyk - [email protected]
