# 🚀 QR Code Temporal Context Processor - Deployment Guide

## 📁 Project Structure

```
gradio-app/
├── app.py                 # Main application (Gradio + MCP)
├── requirements.txt       # Python dependencies
├── test_app.py           # Test suite
├── demo_mcp.py           # MCP functionality demo
├── mcp-config.json       # MCP client configuration
├── README.md             # Project documentation
├── DEPLOYMENT.md         # This deployment guide
└── qr_temporal_data/     # Local data storage (created at runtime)
    └── snapshots.pkl     # Temporal snapshots database
```

## 🛠️ Installation & Setup

### 1. System Dependencies
```bash
# Install zbar library for QR code processing
sudo apt update
sudo apt install -y libzbar0
```

### 2. Python Environment
```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt
```

### 3. Verify Installation
```bash
# Run test suite
python test_app.py
```

## 🚀 Running the Application

### Start the Server
```bash
source venv/bin/activate
python app.py
```

The application will start on `http://localhost:7860` with both:
- **Gradio Web Interface**: For manual interaction
- **MCP Server**: For AI assistant integration

## 🔧 MCP Integration

### Available Tools

1. **`process_qr_code_image`**
   - Process QR code images and extract temporal context
   - Input: Image file path (URL)
   - Output: Detailed analysis with evolution history

2. **`analyze_qr_content_evolution`**
   - Analyze how QR content has changed over time
   - Input: QR content (URL or text)
   - Output: Evolution timeline and change history

3. **`get_qr_historical_context`**
   - Get historical snapshot at specific date
   - Input: QR content + target date (YYYY-MM-DD)
   - Output: Content state at specified time

### MCP Endpoints

- **SSE Endpoint**: `http://localhost:7860/gradio_api/mcp/sse`
- **Schema**: `http://localhost:7860/gradio_api/mcp/schema`

### Cursor Configuration

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "qr_processor": {
      "command": "npx",
      "args": [
        "mcp-remote", 
        "http://localhost:7860/gradio_api/mcp/sse"
      ]
    }
  }
}
```

## 🧪 Testing MCP Functionality

```bash
# Test MCP tools via API
python demo_mcp.py

# Verify schema endpoint
curl http://localhost:7860/gradio_api/mcp/schema
```

## 🌐 Web Interface Features

### Tab 1: QR Code Image Processor
- Upload QR code images (PNG, JPG, etc.)
- Automatic content extraction and analysis
- Real-time temporal context generation

### Tab 2: Content Evolution Analyzer
- Analyze URL/text evolution over time
- Track changes in titles, descriptions, content
- View change history and timestamps

### Tab 3: Historical Context
- Query content state at specific dates
- Reconstruct decision-making context
- Understand temporal information flow

## 📊 Data Storage

- **Location**: `./qr_temporal_data/snapshots.pkl`
- **Format**: Pickled Python dictionary
- **Content**: Timestamped content snapshots
- **Privacy**: All data stored locally

## 🔒 Security Considerations

1. **Local Processing**: All QR decoding happens locally
2. **Web Requests**: Only for URL content fetching
3. **No External APIs**: No third-party data sharing
4. **User Control**: Full control over stored data

## 🌟 Use Cases

### 📋 Product Documentation
```
User uploads QR from 2022 manual
AI: "This QR links to docs updated 3 times since printing. 
     Version 2.1 includes critical safety updates not in your manual."
```

### 🎪 Event Management
```
User scans conference badge QR
AI: "Original session 'AI Future' was moved from Room A to Room B 
     at 2:30 PM on March 15th. Speaker changed to Dr. Chen."
```

### 🏢 Regulatory Compliance
```
User analyzes compliance QR code
AI: "Regulation updated twice since QR creation. Current version 
     includes new safety requirements effective Jan 2024."
```

## 🔄 Continuous Operation

### Background Service (Optional)
```bash
# Run as background service
nohup python app.py > app.log 2>&1 &

# Check status
ps aux | grep app.py
```

## 🐳 Docker Deployment

### Prerequisites
- Docker and Docker Compose installed
- At least 2GB RAM available
- Port 7860 and 27017 available

### Quick Start with Docker Compose

1. **Clone and prepare the environment:**
   ```bash
   git clone <your-repo>
   cd gradio-app
   ```

2. **Set environment variables:**
   Create a `.env` file with:
   ```bash
   # MongoDB Configuration
   MONGODB_CONNECTION_STRING=mongodb://admin:strongpassword123@mongodb:27017/qrcodetcp?authSource=admin
   MONGODB_DATABASE=qrcodetcp
   MONGODB_COLLECTION=content_snapshots
   
   # MongoDB Root Password
   MONGO_ROOT_PASSWORD=strongpassword123
   
   # Application Configuration
   MAX_CONTENT_LENGTH=2000
   ```

3. **Deploy with Docker Compose:**
   ```bash
   docker-compose up -d
   ```

4. **Access the application:**
   - Web Interface: http://localhost:7860
   - MCP Server: http://localhost:7860/gradio_api/mcp/sse
   - MongoDB: localhost:27017

### Individual Container Deployment

1. **Build the application image:**
   ```bash
   docker build -t qr-processor:latest .
   ```

2. **Run MongoDB:**
   ```bash
   docker run -d \
     --name qr-mongodb \
     -p 27017:27017 \
     -e MONGO_INITDB_ROOT_USERNAME=admin \
     -e MONGO_INITDB_ROOT_PASSWORD=strongpassword123 \
     -e MONGO_INITDB_DATABASE=qrcodetcp \
     -v mongodb_data:/data/db \
     mongo:7.0
   ```

3. **Run the QR Processor:**
   ```bash
   docker run -d \
     --name qr-processor \
     -p 7860:7860 \
     -e MONGODB_CONNECTION_STRING="mongodb://admin:strongpassword123@host.docker.internal:27017/qrcodetcp?authSource=admin" \
     -e MONGODB_DATABASE=qrcodetcp \
     -e MONGODB_COLLECTION=content_snapshots \
     --link qr-mongodb:mongodb \
     qr-processor:latest
   ```

## 🌐 Production Deployment

### Using External MongoDB

If you have an existing MongoDB instance:

```bash
docker run -d \
  --name qr-processor \
  -p 7860:7860 \
  -e MONGODB_CONNECTION_STRING="your-mongodb-connection-string" \
  -e MONGODB_DATABASE=qrcodetcp \
  -e MONGODB_COLLECTION=content_snapshots \
  qr-processor:latest
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MONGODB_CONNECTION_STRING` | Full MongoDB connection string | Required |
| `MONGODB_DATABASE` | Database name | `qrcodetcp` |
| `MONGODB_COLLECTION` | Collection name for content snapshots | `content_snapshots` |
| `MAX_CONTENT_LENGTH` | Maximum content length to capture | `2000` |
| `MONGO_ROOT_PASSWORD` | MongoDB root password (for docker-compose) | `strongpassword123` |

### Health Checks

The application includes health checks:
- **HTTP Health Check:** `GET http://localhost:7860`
- **Docker Health Check:** Built into the container
- **Automatic Restart:** Containers restart unless stopped

### Data Persistence

- **MongoDB Data:** Persisted in `mongodb_data` volume
- **Access Logs:** Stored in MongoDB `accessLogs` collection
- **Fallback Storage:** `qr_data` volume for pickle files (if MongoDB fails)

### Monitoring

Check application status:
```bash
# Check container status
docker-compose ps

# View application logs
docker-compose logs qr-processor

# View MongoDB logs
docker-compose logs mongodb

# Check health status
curl -f http://localhost:7860
```

### Scaling and Performance

For high-traffic deployments:
1. Use MongoDB replica sets
2. Implement load balancing with multiple app containers
3. Add Redis for caching
4. Use persistent volumes for data

### Security Considerations

- Change default MongoDB passwords
- Use environment-specific connection strings
- Enable MongoDB authentication
- Consider using Docker secrets for sensitive data
- Run containers as non-root users in production

### Troubleshooting

**Common Issues:**

1. **MongoDB Connection Failed:**
   - Check connection string format
   - Verify MongoDB is running and accessible
   - Check network connectivity between containers

2. **Application Won't Start:**
   - Check MongoDB dependency is healthy
   - Verify environment variables are set
   - Check application logs for errors

3. **Performance Issues:**
   - Monitor MongoDB performance
   - Check available memory and CPU
   - Consider scaling horizontally

**Logs Location:**
```bash
# Application logs
docker logs qr-processor-app

# MongoDB logs
docker logs qr-processor-mongodb
```

## 🛠️ Troubleshooting

### Common Issues

1. **zbar library missing**
   ```bash
   sudo apt install -y libzbar0
   ```

2. **Port already in use**
   ```bash
   # Change port in app.py
   demo.launch(server_port=7861)
   ```

3. **MCP connection issues**
   ```bash
   # Verify server is running
   curl http://localhost:7860/gradio_api/mcp/schema
   ```

### Debug Mode
```bash
# Enable debug logging
export GRADIO_DEBUG=1
python app.py
```

## 📈 Performance Notes

- **Image Processing**: ~1-2 seconds per QR code
- **Web Content Fetch**: ~2-5 seconds per URL
- **Memory Usage**: ~100MB base + snapshots
- **Storage Growth**: ~1KB per content snapshot

## 🔧 Configuration

### Environment Variables
```bash
export GRADIO_MCP_SERVER=True     # Enable MCP server
export GRADIO_DEBUG=1             # Enable debug mode
export GRADIO_SERVER_PORT=7860    # Custom port
```

### Customization
- Modify `app.py` for additional features
- Update `requirements.txt` for new dependencies
- Extend `processor` class for enhanced functionality

---

**🎯 Ready to bridge static QR codes with dynamic temporal context!**

The future of QR code processing is here - making invisible temporal friction visible, one code at a time.