update readme

README.md

@@ -13,42 +13,76 @@ short_description: AI Phone Leaderboard
 
 # AI Phone Benchmark Leaderboard
 
-Streamlit frontend for displaying AI model performance benchmarks across different mobile devices.
+A Streamlit dashboard for displaying and analyzing mobile device AI benchmark results. The dashboard fetches data from Firebase Firestore and provides interactive visualizations and filtering capabilities.
 
-## Features
+## Setup
 
-- Interactive data filtering
-- Performance comparison charts
-- Detailed benchmark leaderboard
-- Real-time data updates
-- Responsive design
+### Prerequisites
+- Python 3.10+
+- Firebase project with Firestore database
+- Hugging Face account (for deployment)
 
-## Local Development
+### Local Development
 
-1. Create a virtual environment:
+1. Clone the repository:
 ```bash
-make venv
+git clone https://github.com/yourusername/ai-phone-leaderboard.git
+cd ai-phone-leaderboard
 ```
 
-2. Install dependencies:
+2. Create a virtual environment and install dependencies:
 ```bash
+make venv
 make setup-dev
 ```
 
-3. Set up environment variables:
-Create a `.env` file:
-```env
-HF_TOKEN=your_hugging_face_token_here  # Required for accessing the API
+### Firebase Configuration
+
+1. Create a Firebase Service Account:
+   - Go to Firebase Console → Project Settings → Service Accounts
+   - Create a new service account for the dashboard:
+     ```bash
+     # Create service account
+     gcloud iam service-accounts create dashboard-firestore-reader \
+         --description="Service account for reading Firestore data in the dashboard" \
+         --display-name="Dashboard Firestore Reader"
+     ```
+   - Grant minimal required permissions:
+     ```bash
+     # Grant Firestore read-only access
+     gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+         --member="serviceAccount:dashboard-firestore-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
+         --role="roles/datastore.viewer"
+     ```
+   - Generate and download the service account key:
+     - Click "Generate New Private Key"
+     - Save the JSON file (don't commit this to git)
+
+2. For local development, create `.streamlit/secrets.toml`:
+```toml
+FIREBASE_CREDENTIALS = '''
+{
+  "type": "service_account",
+  "project_id": "your-project-id",
+  "private_key_id": "your-private-key-id",
+  "private_key": "your-private-key",
+  "client_email": "your-client-email",
+  "client_id": "your-client-id",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "your-client-cert-url",
+  "universe_domain": "googleapis.com"
+}
+'''
 ```
 
-4. Run the application:
+3. Run the application:
 ```bash
 make run
 ```
 
-## Deployment
-
-This application is configured for deployment on Hugging Face Spaces:
+## Deployment to Hugging Face Spaces
 
 1. Create a new Space:
    - Go to huggingface.co/spaces
@@ -56,25 +90,54 @@ This application is configured for deployment on Hugging Face Spaces:
    - Select "Streamlit" as the SDK
    - Choose a name for your space
 
-2. Add required secret:
-   - Go to Space Settings
-   - Under "Repository Secrets"
-   - Add `HF_TOKEN` with your Hugging Face token
+2. Add Firebase credentials to Spaces:
+   - Go to Space Settings → Repository Secrets
+   - Add a new secret named `FIREBASE_CREDENTIALS`
+   - Value should be your Firebase credentials as a minified JSON string (single line)
+   - Note: Convert the private key's newlines to `\n` in the JSON
 
-3. The application will automatically deploy when you push to the repository.
+Example of minified credentials for HF Spaces:
+```json
+{"type":"service_account","project_id":"your-project-id","private_key_id":"your-key-id","private_key":"-----BEGIN PRIVATE KEY-----\\nYour\\nPrivate\\nKey\\nHere\\n-----END PRIVATE KEY-----\\n","client_email":"your-email","client_id":"your-client-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"your-cert-url","universe_domain":"googleapis.com"}
+```
 
-## Configuration
+3. The application will automatically deploy when you push to the repository.
 
-The application can be configured through environment variables:
-- `HF_TOKEN`: Hugging Face access token (required)
-- `API_URL`: Backend API URL (defaults to production)
+## Project Structure
+```
+.
+├── .gitignore
+├── .streamlit/
+│   └── secrets.toml
+├── requirements/
+│   ├── base.txt
+│   ├── dev.txt
+│   └── prod.txt
+├── src/
+│   ├── components/
+│   │   ├── filters.py
+│   │   ├── header.py
+│   │   └── visualizations.py
+│   ├── core/
+│   │   └── config.py
+│   └── services/
+│       └── firebase.py
+├── main.py
+└── requirements.txt
+```
 
-## API Integration
+## Firebase Data Structure
 
-The application integrates with the AI Phone Benchmark API for data retrieval:
-- Leaderboard data
-- Performance metrics
-- Device information
+The application expects the following Firestore collection structure:
+```
+benchmarks/
+└── v1/
+    └── submissions/
+        └── [benchmark_uuid]/
+            ├── benchmarkResult: {...}
+            ├── deviceInfo: {...}
+            └── metadata: {...}
+```
 
 ## Development
 
@@ -88,4 +151,35 @@ make lint          # Run code linter
 make format        # Format code using black
 make test          # Run tests
 make clean         # Clean cache files
-```
+```
+
+## Security Considerations
+
+1. Never commit sensitive credentials to git:
+```gitignore
+# Add to .gitignore
+.streamlit/secrets.toml
+*firebase*.json
+```
+
+2. Use environment-specific secrets:
+   - Local: Use `.streamlit/secrets.toml`
+   - Production: Use HF Spaces secrets
+
+3. Firebase Security:
+   - Create a dedicated service account with minimal permissions
+   - Only grant read access to the required Firestore collections
+
+## Dependencies
+
+Key dependencies are pinned to specific versions to ensure stability:
+```
+firebase-admin==6.6.0
+streamlit>=1.28.0
+pandas>=2.1.3
+plotly>=5.18.0
+```
+
+## License
+
+[MIT License](LICENSE)