Skip to content

File Structure

Jump to bottom
github-actions edited this page Oct 22, 2025 · 1 revision

File Structure

Project Organization

muze/
├── .git/                           # Git version control
├── .github/                        # GitHub configuration
│   └── workflows/
│       └── doc-analysis.yml        # CI/CD workflow for documentation
├── docs/                           # Documentation wiki (this directory)
│   ├── README.md                   # Documentation index
│   ├── Overview.md                 # Project overview
│   ├── Architecture.md             # System architecture
│   ├── API-Reference.md            # API documentation
│   ├── Data-Flow.md                # Data flow diagrams
│   ├── Emotion-Detection.md        # Emotion detection details
│   ├── Music-Classification.md     # Music system details
│   ├── Frontend.md                 # Frontend documentation
│   ├── Installation.md             # Setup instructions
│   ├── Quick-Start.md              # Quick start guide
│   ├── File-Structure.md           # This file
│   ├── Configuration.md            # Configuration guide
│   ├── CI-CD.md                    # CI/CD documentation
│   ├── Troubleshooting.md          # Problem solving
│   ├── Contributing.md             # Contribution guidelines
│   └── Data-Sources.md             # Data credits
├── scripts/                        # Utility scripts
│   └── update_docs.py              # Auto-documentation generator
├── snapshots/                      # Temporary webcam captures
│   └── pic.png                     # Latest snapshot (overwritten)
├── static/                         # Static assets
│   ├── music/                      # Audio files
│   │   ├── 001.mp3                 # Song 1
│   │   ├── 002.mp3                 # Song 2
│   │   └── ...                     # Songs 3-903
│   ├── graph.jpg                   # Generated emotion visualization
│   └── jquery-1.7.1.min.js         # jQuery library
├── templates/                      # Jinja2 HTML templates
│   ├── base.html                   # Base template
│   ├── musi.html                   # Main music player
│   ├── init.html                   # Webcam test page
│   ├── index.html                  # Landing page
│   ├── trial.html                  # Development page
│   ├── showgraph.html              # Graph display
│   └── styling.css                 # CSS styles
├── __pycache__/                    # Python bytecode cache
├── app.py                          # Flask application (main entry)
├── algorithmia.py                  # Emotion detection & playlist logic
├── test.txt                        # Song database (pickled list)
├── LICENSE                         # License file
├── README.md                       # Project README
└── Plutchik-Model-600.png          # Emotion wheel reference image

Core Files

app.py

Purpose: Main Flask application entry point

Size: ~1 KB

Key Components:

  • Flask app initialization
  • Route definitions (/, /hook, /graph)
  • Image processing logic
  • Server configuration

Dependencies:

  • flask
  • algorithmia (local module)
  • PIL (Pillow)
  • base64, re, io

Routes:

@app.route('/')              # Main page
@app.route('/hook')          # Snapshot upload
@app.route('/graph')         # Emotion visualization

algorithmia.py

Purpose: Emotion detection and playlist generation

Size: ~3.5 KB

Key Functions:

  • get_emotion() - Detect emotion from snapshot
  • get_playlist() - Generate personalized playlist
  • get_emotion_grid() - Create emotion visualization

External Dependencies:

  • Algorithmia API
  • test.txt song database

Global Variables:

  • emot_list - Emotion history tracker

test.txt

Purpose: Song database

Format: Pickled Python list (Python 2 protocol)

Size: ~37 KB

Contents: 903 song entries

Structure:

["Song Name - Artist", ...]

Encoding: Latin-1

Loading:

with open("test.txt", "rb") as fp:
    songnames = pickle.load(fp, encoding='latin1')

Template Files

templates/base.html

Purpose: Base template for inheritance

Size: ~361 bytes

Features:

  • Common HTML structure
  • jQuery inclusion
  • CSS stylesheet link
  • Content block definition

Used By: Other templates via {% extends "base.html" %}

templates/musi.html

Purpose: Main music player interface

Size: ~3.5 KB

Features:

  • Webcam capture
  • Audio playback
  • Playlist management
  • User controls

Template Variables:

  • songs - Playlist array from backend

JavaScript:

  • WebRTC setup
  • Snapshot capture
  • Audio event handlers
  • AJAX communication

templates/init.html

Purpose: Webcam initialization test page

Size: ~2 KB

Use Case: Testing webcam functionality

Features:

  • Basic webcam setup
  • Snapshot capture
  • Minimal UI

templates/index.html

Purpose: Simple landing page

Size: ~61 bytes

Content: Minimal placeholder

templates/trial.html

Purpose: Development/testing page

Size: ~2.3 KB

Use Case: Experimental features

templates/showgraph.html

Purpose: Display emotion graph

Size: ~137 bytes

Content: Image display for static/graph.jpg

templates/styling.css

Purpose: CSS styles

Size: ~967 bytes

Styles: UI components, layout, colors

Static Assets

static/music/

Purpose: Audio file storage

File Count: 903 MP3 files

Naming: 001.mp3 to 903.mp3 (zero-padded)

Total Size: ~2-3 GB (estimated)

Format: MP3 audio

Access: Served directly by Flask

URL Pattern: /static/music/XXX.mp3

static/jquery-1.7.1.min.js

Purpose: jQuery library

Version: 1.7.1 (legacy)

Size: ~93 KB (minified)

Usage: AJAX, DOM manipulation, event handling

Note: Consider upgrading to latest version

static/graph.jpg

Purpose: Emotion history visualization

Generated By: get_emotion_grid() function

Size: ~50-100 KB

Format: JPEG image

Dimensions: Variable (matplotlib default)

Lifecycle: Overwritten each time graph is generated

Temporary Files

snapshots/pic.png

Purpose: Latest webcam snapshot

Size: ~50-150 KB

Format: RGB PNG (400×350)

Lifecycle:

  • Created on snapshot capture
  • Overwritten on next capture
  • Not persisted long-term

Privacy: Contains user's facial image

Configuration Files

.github/workflows/doc-analysis.yml

Purpose: GitHub Actions workflow

Triggers: Pull requests (opened, synchronized, reopened)

Actions:

  1. Checkout code
  2. Setup Python 3.11
  3. Install dependencies
  4. Run analysis script

Environment Variables:

  • GITHUB_TOKEN
  • PR_NUMBER
  • REPO
  • BASE_SHA
  • HEAD_SHA

Utility Scripts

scripts/update_docs.py

Purpose: Auto-generate documentation

Size: ~2 KB

Features:

  • Analyze undocumented functions
  • Generate doc templates
  • Commit to repository

Dependencies:

  • analyze_pr.py (referenced but not present)

Usage: Called by CI/CD pipeline

Generated Files

pycache/

Purpose: Python bytecode cache

Contents: .pyc files

Generated By: Python interpreter

Safe to Delete: Yes (regenerated automatically)

Ignore in Git: Yes

Missing/Optional Files

requirements.txt

Status: Not present (should be created)

Purpose: Python dependency list

Recommended Content:

Flask==0.12.2
Algorithmia>=1.0.0
Pillow==5.0.0
numpy==1.14.0
matplotlib==2.1.2
Jinja2==2.10

.env

Status: Not present (should be created)

Purpose: Environment variables

Recommended Content:

ALGORITHMIA_API_KEY=your_key_here
FLASK_SECRET_KEY=your_secret_here
FLASK_ENV=development

.gitignore

Status: May not be comprehensive

Recommended Content:

__pycache__/
*.pyc
*.pyo
.env
snapshots/*.png
static/graph.jpg
venv/
.DS_Store

File Permissions

Required Permissions

Path Read Write Execute
app.py ✅ ❌ ✅
algorithmia.py ✅ ❌ ❌
test.txt ✅ ❌ ❌
templates/ ✅ ❌ ❌
static/music/ ✅ ❌ ❌
snapshots/ ✅ ✅ ✅
static/graph.jpg ✅ ✅ ❌

Storage Requirements

Minimum Disk Space

Component Size
Python code ~10 KB
Templates ~10 KB
Song database ~40 KB
Music files ~2-3 GB
Dependencies ~100 MB
Total ~2.5-3.5 GB

Runtime Storage

Component Size
Snapshots ~150 KB
Graph images ~100 KB
Logs Variable
Cache ~10 MB

File Dependencies

Dependency Graph

app.py
├── algorithmia.py
│   ├── test.txt
│   └── snapshots/pic.png
├── templates/musi.html
│   ├── templates/base.html
│   └── static/jquery-1.7.1.min.js
└── static/music/*.mp3

algorithmia.py
├── test.txt
├── snapshots/pic.png
└── static/graph.jpg (output)

Import Structure

app.py Imports

import flask
from flask import request
from algorithmia import get_playlist, get_emotion_grid
import numpy as np
from PIL import Image
import re
from io import BytesIO
import base64

algorithmia.py Imports

import Algorithmia
import json
import pickle
import random
from PIL import Image
import numpy as np
import matplotlib.pyplot as plt
import mpld3
from matplotlib import colors
import matplotlib.patches as mpatches

File Naming Conventions

Python Files

  • Snake_case: algorithmia.py, update_docs.py
  • Lowercase: All Python modules

Template Files

  • Lowercase: musi.html, base.html
  • Descriptive: Names indicate purpose

Music Files

  • Zero-padded numbers: 001.mp3, 045.mp3, 903.mp3
  • Three digits: Consistent width

Image Files

  • Lowercase: graph.jpg, pic.png
  • Descriptive: Purpose clear from name

Backup Recommendations

Critical Files (Must Backup)

  • app.py
  • algorithmia.py
  • test.txt
  • templates/
  • static/music/ (if custom)

Generated Files (Don't Backup)

  • __pycache__/
  • snapshots/pic.png
  • static/graph.jpg

Configuration Files (Backup Separately)

  • .env (if created)
  • API keys (secure storage)

Development vs Production

Development Files

  • templates/trial.html
  • templates/init.html
  • scripts/update_docs.py
  • Debug logs

Production Files

  • app.py
  • algorithmia.py
  • templates/musi.html
  • static/
  • test.txt

Excluded in Production

  • .git/
  • __pycache__/
  • Development templates
  • Test scripts
  • Documentation source

File Modification Frequency

File Frequency Reason
snapshots/pic.png Every 20 songs Emotion rechecks
static/graph.jpg On demand User requests report
app.py Rarely Code updates
algorithmia.py Rarely Algorithm changes
test.txt Never Static database
templates/ Rarely UI updates
static/music/ Never Static library

Security Considerations

Sensitive Files

  • algorithmia.py (contains API key)
  • .env (if created)
  • snapshots/pic.png (user images)

Public Files

  • templates/
  • static/music/
  • README.md

Recommendations

  • Never commit API keys
  • Add .env to .gitignore
  • Clear snapshots periodically
  • Use environment variables for secrets

Clone this wiki locally