Upload README.md

README.md

@@ -0,0 +1,177 @@
+---
+title: DocumentVault
+emoji: 📁
+colorFrom: blue
+colorTo: purple
+sdk: docker
+sdk_version: "0.0.0"
+app_file: app.py
+app_port: 7860
+pinned: false
+short_description: Document vault with Hugging Face-backed storage
+---
+
+# DocVault - Offline-First Document Storage System
+
+Complete document storage system built with **Python Flask** and Hugging Face Hub-backed persistence. Uploads are committed to a Hugging Face repository, so files remain available after app restarts and across sessions.
+
+## 🎯 Features
+
+### Core Features
+- ✅ **Create Files and Folders** - Including nested directory structures
+- ✅ **Delete Items** - Individual files/folders or bulk deletion
+- ✅ **Upload Files** - Support for 50+ file types
+- ✅ **List Contents** - Browse file/folder hierarchy with metadata
+- ✅ **Rename Items** - Rename files and folders
+- ✅ **Security** - Path traversal prevention, input validation
+- ✅ **Logging** - Comprehensive logging with rotation
+- ✅ **File Metadata** - Size, creation time, modification time
+- ✅ **Multi-User** - Support for multiple users via user IDs
+
+### Storage
+- Persistent storage in a Hugging Face repository configured by `HF_REPO_ID`
+- Files are written through `huggingface_hub` commit APIs, not the local container filesystem
+- Automatic marker files (`.gitkeep`) preserve folder structure in the repo
+- Prevents duplicate filenames with auto-numbering
+- Maintains clean directory structure
+
+## 📁 Project Structure
+
+```
+.
+├── server/
+│   ├── app.py              # Flask application
+│   ├── config.py           # Configuration settings
+│   ├── requirements.txt    # Python dependencies
+│   ├── routes/
+│   │   └── api.py          # API endpoints
+│   ├── storage/
+│   │   └── manager.py      # Storage operations
+│   └── utils/
+│       ├── logger.py       # Logging setup
+│       └── validators.py   # Path validation & security
+├── data/                   # Storage directory (auto-created)
+├── logs/                   # Log files (auto-created)
+├── tests/
+│   ├── test_docvault.py   # Unit tests
+│   └── test_api.sh        # API test script
+├── index.html              # Frontend UI
+├── app.js                  # Frontend app logic
+├── styles.css              # Frontend styles
+└── README.md               # This file
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python 3.8+
+- pip or conda
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <your-repo-url>
+   cd DocVault
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r server/requirements.txt
+   ```
+
+3. **Run the application**
+   ```bash
+   python server/app.py
+   ```
+
+4. **Access the app**
+   - Open browser to `http://localhost:5000`
+
+## 📝 API Endpoints
+
+### File Operations
+- `POST /api/create` - Create file or folder
+- `DELETE /api/delete` - Delete file or folder
+- `PUT /api/rename` - Rename item
+- `POST /api/upload` - Upload file
+- `GET /api/list/<path>` - List directory contents
+
+### Request Examples
+
+**Create File:**
+```bash
+curl -X POST http://localhost:5000/api/create \
+  -H "Content-Type: application/json" \
+  -d '{"user_id":"default_user","item_type":"file","name":"test.txt","path":"/"}'
+```
+
+**Upload File:**
+```bash
+curl -X POST http://localhost:5000/api/upload \
+  -F "user_id=default_user" \
+  -F "file=@localfile.txt" \
+  -F "path=/"
+```
+
+**List Contents:**
+```bash
+curl http://localhost:5000/api/list/default_user/
+```
+
+## 🧪 Testing
+
+Run the test suite:
+```bash
+python -m pytest tests/test_docvault.py -v
+```
+
+Or use the included API test script:
+```bash
+bash tests/test_api.sh
+```
+
+## 🔒 Security Features
+
+- **Path Traversal Prevention** - Validates all paths to prevent directory escape attacks
+- **Input Validation** - Sanitizes filenames and paths
+- **User Isolation** - Each user has their own data directory
+- **Error Handling** - Comprehensive error messages without exposing system details
+
+## 📊 Logging
+
+- Logs stored in `logs/` directory
+- Automatic log rotation (10 MB per file, 10 files kept)
+- Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+## 🚢 Deployment
+
+### Docker
+```bash
+docker build -t docvault .
+docker run -p 5000:5000 docvault
+```
+
+### Hugging Face Spaces
+This app is designed to run on Hugging Face Spaces with a Flask backend and persistent Hub storage.
+
+## 📦 Dependencies
+
+- Flask 2.3.2
+- Werkzeug 2.3.6
+- Python 3.8+
+
+See `server/requirements.txt` for full list.
+
+## 📄 License
+
+MIT License
+
+## 🤝 Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## 📧 Support
+
+For issues or questions, please open an Issue on GitHub.
+