SonicFlow 🎧 [ST_TERMINAL]

SonicFlow is a sleek, terminal-inspired music discovery application built with Python, Flask, industry-standard security practices, and the iTunes Search API. It features a "Noir Terminal" aesthetic, allowing users to scan global audio repositories, save tracks to a persistent "Vault," and decrypt a daily selection of music.

---

🌌 Features

• [SYSTEM_DISCOVERY]: Real-time music search via iTunes API with filters for Artist, Album, and Genre.
• [LIBRARY_VAULT]: Save your favorite tracks to a local SQLite database for future retrieval.
• [DECRYPT_DAILY]: A daily curated selection of 10 tracks seeded by the current date.
• Global Player: Integrated audio preview player with "Noir" visual scanlines and effects.
• Responsive Layout: Built with a custom "Noir Terminal" CSS stylesheet and Bootstrap grid.
• Paginated Results: Low-latency handling of search results and history vault lists.

---

🛡️ Security Architecture

To ensure the application is safe for public environments, the codebase implements the following protection layers:

1. CSRF Protection: All state-changing routes (POST requests for saving/deleting songs) are protected via a session-signed, cryptographically compared CSRF token check.
2. XSS Mitigation: Client-side rendering in the search module uses robust HTML entity encoding to sanitize user/API input, protecting against DOM-based Cross-Site Scripting.
3. Strict Content Security Policy (CSP): HTTP response headers restrict resource loading to local files ('self') and trusted CDNs, preventing unauthorized script execution and code injection.
4. Secure Cookie Configuration: Cookies are hardened with HttpOnly, SameSite=Lax, and Secure attributes (enforced in production) to prevent session-hijacking.
5. Secure Fallback Key: The application automatically generates a cryptographically secure random key (secrets.token_hex(32)) if no SECRET_KEY is provided in the environment.

---

🛠️ Tech Stack

• Backend: Python 3.11+, Flask
• Database: SQLite with Flask-SQLAlchemy (ORM)
• Frontend: Vanilla JS (CSP-Compliant, Event Delegation), Jinja2 Templates, Bootstrap 4
• Testing: Pytest (configured to bypass CSRF validation during unit testing)
• API Integration: iTunes Search API (restricted via CSP to is*-ssl.mzstatic.com and *.apple.com)

---

🚀 Getting Started

Prerequisites

• Python 3.11 or higher
• pip (Python package manager)

Installation

1. Clone the Repository

   git clone https://github.com/yourusername/SonicFlow.git
   cd SonicFlow

2. Setup Virtual Environment

   python -m venv venv
   # Windows:
   venv\Scripts\activate
   # macOS/Linux:
   source venv/bin/activate

3. Install Pinned Dependencies

   pip install -r requirements.txt

4. Environment Configuration Copy the example environment file:

   cp .env.example .env

   Open the new .env file and configure your security keys:

   SECRET_KEY=generate-a-secure-random-key-here
   DATABASE_URL=sqlite:///music.db

5. Initialize Database & Run

   python run.py

   Open your browser to http://127.0.0.1:5000.

---

🧪 Running Tests

Verify the backend services, models, and test client routes:

python -m pytest -v

---

📖 Additional Documentation

• LEARN.md: Beginner's guide detailing how the application works, along with core concepts about web security (XSS, CSRF, CSP).