Knowledge Graph Explorer - Google Cloud Run Deployment

A powerful interactive knowledge graph system that transforms documents into queryable knowledge networks with natural language Q&A capabilities.

🌟 Features

• Document Processing: Upload TXT files and process web URLs
• Interactive Visualization: D3.js-powered graph with drag, zoom, and pan
• Entity Recognition: Automatic extraction of people, organizations, locations, products
• Relationship Mapping: Discover connections between entities
• Natural Language Q&A: Ask questions about your knowledge graph
• Real-time Analytics: Live statistics and updates

🚀 Quick Deployment to Google Cloud Run

Prerequisites

1. Google Cloud Account: Create one here
2. Google Cloud SDK: Install gcloud CLI
3. Docker (optional): For local testing

Step 1: Setup Google Cloud Project

# Create a new project (optional)
gcloud projects create your-project-id --name="Knowledge Graph Explorer"

# Set your project ID
gcloud config set project your-project-id

# Enable billing (required for Cloud Run)
# Visit: https://console.cloud.google.com/billing

Step 2: Deploy with One Command

# Edit deploy.sh and set your PROJECT_ID
nano deploy.sh

# Run the deployment script
./deploy.sh

That's it! Your Knowledge Graph Explorer will be live in minutes.

🔧 Manual Deployment (Alternative)

If you prefer manual control:

1. Enable APIs

gcloud services enable cloudbuild.googleapis.com
gcloud services enable run.googleapis.com
gcloud services enable containerregistry.googleapis.com

2. Build and Deploy

# Build the container
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/knowledge-graph-explorer

# Deploy to Cloud Run
gcloud run deploy knowledge-graph-explorer \
  --image gcr.io/YOUR_PROJECT_ID/knowledge-graph-explorer \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --memory 2Gi \
  --cpu 1 \
  --max-instances 10 \
  --port 8080

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Frontend│    │   Flask Backend  │    │   spaCy NLP     │
│   - D3.js Graph │◄──►│   - REST API     │◄──►│   - Entity Ext. │
│   - File Upload │    │   - CORS Enabled │    │   - Relationships│
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Static Assets  │    │   SQLite DB      │    │  Knowledge Graph│
│  - HTML/CSS/JS  │    │   - Documents    │    │  - Nodes/Edges  │
│  - Images       │    │   - Entities     │    │  - Relationships│
└─────────────────┘    └──────────────────┘    └─────────────────┘

🔒 Security & Configuration

Environment Variables

Create a .env file (copy from .env.example):

SECRET_KEY=your-super-secret-key-here
FLASK_ENV=production
DATABASE_URL=postgresql://user:pass@host:port/db  # Optional
MAX_CONTENT_LENGTH=104857600  # 100MB

Security Features

• ✅ CORS properly configured
• ✅ File upload size limits
• ✅ Non-root container user
• ✅ Environment-based configuration
• ✅ Production-ready Gunicorn server

📊 Monitoring & Scaling

Cloud Run Features

• Auto-scaling: 0 to 10 instances based on traffic
• Pay-per-use: Only charged when processing requests
• Health checks: Automatic restart on failures
• HTTPS: SSL certificate included
• Global CDN: Fast worldwide access

Monitoring

# View logs
gcloud run services logs read knowledge-graph-explorer --region=us-central1

# Monitor metrics
gcloud run services describe knowledge-graph-explorer --region=us-central1

🛠️ Local Development

Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download spaCy model
python -m spacy download en_core_web_sm

# Run locally
python src/main.py

Docker Testing

# Build image
docker build -t knowledge-graph-explorer .

# Run container
docker run -p 8080:8080 knowledge-graph-explorer

📈 Usage Examples

1. Upload Documents

• Drag and drop TXT files
• Maximum 100MB total across all documents
• Automatic entity extraction and relationship mapping

2. Process URLs

• Enter web page URLs
• Content extraction and processing
• Integration with existing knowledge graph

3. Natural Language Queries

• "What companies does Elon Musk lead?"
• "How is Tesla connected to SpaceX?"
• "What locations are mentioned in the documents?"

4. Interactive Exploration

• Drag nodes to reorganize the graph
• Zoom and pan for detailed exploration
• Hover for entity information
• Color-coded entity types

💰 Cost Estimation

Google Cloud Run pricing (as of 2024):

• CPU: $0.00002400 per vCPU-second
• Memory: $0.00000250 per GiB-second
• Requests: $0.40 per million requests
• Free tier: 2 million requests/month

Estimated monthly cost for moderate usage: $5-20

🔄 Updates & Maintenance

Updating the Application

# Make your changes
git add .
git commit -m "Update application"

# Redeploy
./deploy.sh

Backup Data

# Export SQLite database (if using default storage)
gcloud run services proxy knowledge-graph-explorer --port=8080
# Then use database export tools

🆘 Troubleshooting

Common Issues

1. Build Failures

   • Check Docker syntax in Dockerfile
   • Verify all dependencies in requirements.txt

2. Memory Issues

   • Increase memory allocation in cloudbuild.yaml
   • Optimize spaCy model usage

3. Permission Errors

   • Ensure proper IAM roles
   • Check service account permissions

Getting Help

• Google Cloud Support: Cloud Console
• Documentation: Cloud Run Docs
• Community: Stack Overflow

📄 License

This project is open source and available under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

---

Built with ❤️ using Flask, React, D3.js, and spaCy