add readme

README.md

@@ -0,0 +1,114 @@
+# Audio File Upload App
+
+A minimalistic web application for uploading and managing MP3/WAV audio files with real-time updates.
+
+## Overview
+
+This application provides a simple interface to upload audio files (MP3, WAV) to a local server. It includes both a web UI and API endpoints, using WebSockets for real-time file list updates.
+
+## Features
+
+- File upload for MP3 and WAV audio files
+- Duplicate file detection
+- Real-time file list updates via WebSockets
+- RESTful API endpoints
+- Minimalistic UI
+
+## Technical Details
+
+- **Backend**: FastAPI
+- **Frontend**: Vanilla HTML/CSS/JavaScript
+- **Template Engine**: Jinja2
+- **Real-time Updates**: WebSockets
+- **File Storage**: Local filesystem
+
+## Installation
+
+1. Clone this repository:
+   ```
+   git clone <repository-url>
+   cd audio-file-upload
+   ```
+
+2. Create a virtual environment:
+   ```
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install dependencies:
+   ```
+   pip install fastapi uvicorn python-multipart jinja2 pillow
+   ```
+
+4. Create favicon (one-time setup):
+   ```
+   python create_favicon.py
+   ```
+
+## Usage
+
+1. Start the server:
+   ```
+   uvicorn main:app --reload
+   ```
+
+2. Access the web interface:
+   ```
+   http://127.0.0.1:8000/
+   ```
+
+3. API Endpoints:
+   - `GET /` - Web interface
+   - `POST /upload` - Upload audio files
+   - `GET /files` - List all uploaded files
+   - `WebSocket /ws` - Real-time file updates
+
+## File Structure
+
+```
+project/
+├── main.py                # FastAPI backend
+├── templates/
+│   └── index.html         # HTML template
+├── static/
+│   └── favicon.ico        # Site favicon
+├── uploads/               # Directory for uploaded files
+└── create_favicon.py      # Script to create favicon
+```
+
+## Development History
+
+This project was developed incrementally with the following features:
+1. Initial implementation with basic file upload capability
+2. Added template-based frontend
+3. Implemented favicon to eliminate 404 errors
+4. Added duplicate file detection
+5. Implemented file listing dashboard
+6. Enhanced with WebSockets for real-time updates
+
+## TODOs
+
+- [ ] Add file size limits for uploads
+- [ ] Implement content validation for audio files
+- [ ] Add better error handling and logging
+- [ ] Consider adding authentication if needed
+- [ ] Add filename sanitization
+- [ ] Implement disk quota management
+
+## Security Considerations
+
+This application is designed for personal use in a controlled environment. Consider the following if deploying more broadly:
+
+- The app has no authentication or authorization
+- No rate limiting is implemented
+- No content validation beyond file extension checks
+- No encryption for data at rest
+
+## Notes for AI Assistants
+
+The application follows these design principles:
+1. Minimalism - Keep code simple and focused on core functionality
+2. Real-time updates - Use WebSockets instead of polling
+3. API-first - All functionality available via API endpoints
+4. Template-based - Frontend uses Jinja2 templates for easy modification