Deployment Guide

Overview

Network Analysis is a 100% client-side application—it consists of static HTML, CSS, and JavaScript files with no backend required. This makes deployment extremely simple: just serve the files with any web server or static hosting service.

All data processing happens in the browser using JavaScript libraries loaded from CDNs. No data is sent to a server.

Quick Start (Local Development)

The fastest way to run Network Analysis locally:

python3 -m http.server 8000
# Then open http://localhost:8000

Do not open index.html directly via file:// protocol. This will cause CORS errors when loading CDN libraries. Always use an HTTP server.

Project Structure

The application consists of these files:

network-analysis/
├── index.html        # Main layout, tabs, CDN imports
├── app.js            # Core logic: data processing, rendering
├── presentation.js   # Event listeners, UI interactions
├── styles.css        # All styling
└── README.md         # Project documentation

File Descriptions

index.html (203 lines)

HTML structure for sidebar, tabs, and visualization containers
Loads all dependencies via CDN links:
- SheetJS (XLSX) for Excel parsing
- D3.js + d3-sankey for Sankey diagrams
- vis-network for force-directed graphs
- Leaflet for geographic maps

app.js (2,160 lines)

Global app state (appState object)
File loading and Excel parsing
Column mapping logic
Data aggregation and indexing
Rendering functions for all 4 visualizations
Filter update handlers

presentation.js (~90 lines)

Event delegation for user interactions
Separates presentation layer from business logic

styles.css

Layout: sidebar, tabs, toolbars
Visualization container styling
Responsive design

Deployment Options

Option 1: GitHub Pages

Ideal for open-source projects or public demos.

Create a GitHub Repository

Push your files to a new repository:

git init
git add index.html app.js presentation.js styles.css README.md
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/network-analysis.git
git push -u origin main

Enable GitHub Pages

Go to repository Settings → Pages
Source: Deploy from a branch
Branch: main → / (root)
Click Save

Access Your Site

Your app will be available at:

https://yourusername.github.io/network-analysis/

GitHub Pages typically deploys within 1-2 minutes.

GitHub Pages is completely free for public repositories. For private repos, you need a GitHub Pro account.

Option 2: Netlify

Best for continuous deployment with drag-and-drop simplicity.

Create Netlify Account

Deploy via Drag-and-Drop

Open Netlify Drop
Drag your project folder into the drop zone
Netlify builds and deploys instantly

Get Your URL

Netlify provides a random subdomain:

https://random-name-12345.netlify.app

You can customize this in Site settings → Change site name

Netlify with Git

For continuous deployment:

Push code to GitHub/GitLab/Bitbucket
In Netlify: New site from Git
Select repository
Build settings:
- Build command: (leave empty)
- Publish directory: . (current directory)
Click Deploy site

Every push to main triggers automatic redeployment.

Option 3: Vercel

Ideal for projects already on GitHub with instant deployment.

Import from GitHub

Sign in at vercel.com
Click New Project
Import your repository

Configure (minimal)

Vercel auto-detects static sites:

Framework Preset: Other
Root Directory: ./
No build command needed

Deploy

Click Deploy — your app is live in ~30 seconds:

https://your-project.vercel.app

Option 4: AWS S3 + CloudFront

For production deployments with full control.

Create S3 Bucket

aws s3 mb s3://network-analysis-app
aws s3 website s3://network-analysis-app \
  --index-document index.html

Upload Files

aws s3 sync . s3://network-analysis-app \
  --exclude ".git/*" \
  --exclude "README.md"

Configure Public Access

Bucket Policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "PublicReadGetObject",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::network-analysis-app/*"
  }]
}

Optional: CloudFront CDN

Create CloudFront distribution
Origin: your S3 bucket endpoint
Enable HTTPS
Add custom domain (requires Route 53 or external DNS)

Option 5: Self-Hosted Server

For internal company networks or on-premise deployments.

server {
    listen 80;
    server_name network-analysis.company.com;
    
    root /var/www/network-analysis;
    index index.html;
    
    location / {
        try_files $uri $uri/ =404;
    }
    
    # Enable compression
    gzip on;
    gzip_types text/html text/css application/javascript;
}

Configuration & Customization

Updating Library Versions

All dependencies are loaded from CDN in index.html (lines 186-196):

<!-- XLSX Parser -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/xlsx.full.min.js"></script>

<!-- D3 and D3-Sankey -->
<script src="https://d3js.org/d3.v7.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/d3-sankey.min.js"></script>

<!-- Vis-Network -->
<script src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>

<!-- Leaflet -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/leaflet.min.js"></script>

If you update library versions, test thoroughly—API changes may break existing functionality.

Offline Mode (Optional)

To run without internet connectivity:

Download Libraries

Save all CDN scripts locally:

mkdir libs
cd libs
curl -O https://cdn.jsdelivr.net/npm/[email protected]/dist/xlsx.full.min.js
curl -O https://d3js.org/d3.v7.min.js
# ... download all libraries

Update index.html

Replace CDN URLs with local paths:

<script src="./libs/xlsx.full.min.js"></script>
<script src="./libs/d3.v7.min.js"></script>
<!-- etc -->

Test Locally

python3 -m http.server 8000
# Disconnect internet and verify it works

Custom Branding

Edit these elements in index.html and styles.css:

<!-- index.html line 6 -->
<title>Your Company - Network Analysis</title>

<!-- Add logo in sidebar -->
<div class="sidebar-section">
    <img src="logo.png" alt="Company Logo" style="max-width: 150px;">
    <h2 class="sidebar-title">Data Source</h2>
    ...
</div>

Security Considerations

Data Privacy: All Excel files are processed entirely in the user’s browser—no data is uploaded to a server. Make this clear to users if handling sensitive data.

HTTPS Requirement

For production deployments, always use HTTPS:

GitHub Pages: HTTPS enabled by default
Netlify/Vercel: Automatic SSL certificates
AWS CloudFront: Configure ACM certificate
Self-hosted: Use Let’s Encrypt

Content Security Policy

If you add CSP headers, whitelist CDN domains:

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' 
    https://cdn.jsdelivr.net 
    https://d3js.org 
    https://unpkg.com 
    https://cdnjs.cloudflare.com;
  style-src 'self' https://cdnjs.cloudflare.com;
  img-src 'self' data: https://*.tile.openstreetmap.org https://*.basemaps.cartocdn.com;

Performance Optimization

Enable Compression

Most hosting platforms enable gzip/brotli automatically. For self-hosted:NGINX:

gzip on;
gzip_types text/html text/css application/javascript application/json;
gzip_min_length 1000;

Apache:

<IfModule mod_deflate.c>
  AddOutputFilterByType DEFLATE text/html text/css application/javascript
</IfModule>

Browser Caching

Set cache headers for static assets:

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Monitoring & Analytics

Since the app is client-side, add analytics via:

Google Analytics

Add to index.html before </head>:

<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Plausible Analytics (Privacy-Friendly)

<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>

Troubleshooting

White Screen / Nothing Loads

Causes:

Opened via file:// instead of HTTP server
CDN libraries blocked by firewall/ad-blocker
JavaScript disabled in browser

Solutions:

Always use HTTP server (see Quick Start)
Check browser console (F12) for errors
Verify CDN URLs are accessible
Try different browser

CORS Errors in Console

Access to script at 'file://...' from origin 'null' has been blocked by CORS

Solution: Use HTTP server, not file:// protocol.

Slow Performance with Large Files

Browser-based processing has limits
Recommend files under 10MB / 10,000 rows
Use Top-N filters aggressively
Consider pre-aggregating data in Excel before loading

Updates & Maintenance

To update your deployed instance:

Pull Latest Changes

git pull origin main

Test Locally

python3 -m http.server 8000
# Verify everything works

Deploy

GitHub Pages: Push to main branch (auto-deploys)
Netlify/Vercel: Push to Git (auto-deploys)
S3: aws s3 sync . s3://bucket-name
Self-hosted: Copy files to web root

Next Steps

Data Format

Review Excel file requirements

Column Mapping

Learn column mapping workflow

Support

For deployment issues:

Check browser console (F12) for JavaScript errors
Verify all CDN libraries load successfully
Test with a small sample Excel file first
Review README.md in the source repository

Get Started

Visualizations

Guides

Overview

Quick Start (Local Development)

Project Structure

Deployment Options

Option 1: GitHub Pages

Option 2: Netlify

Option 3: Vercel

Option 4: AWS S3 + CloudFront

Option 5: Self-Hosted Server

Configuration & Customization

Updating Library Versions

Offline Mode (Optional)

Custom Branding

Security Considerations

HTTPS Requirement

Content Security Policy

Performance Optimization

Monitoring & Analytics

Google Analytics

Plausible Analytics (Privacy-Friendly)

Troubleshooting

Updates & Maintenance

Next Steps

Data Format

Column Mapping

Support

Build docs developers (and LLMs) love

Get Started

Visualizations

Guides

​Overview

​Quick Start (Local Development)

​Project Structure

​Deployment Options

​Option 1: GitHub Pages

​Option 2: Netlify

​Option 3: Vercel

​Option 4: AWS S3 + CloudFront

​Option 5: Self-Hosted Server

​Configuration & Customization

​Updating Library Versions

​Offline Mode (Optional)

​Custom Branding

​Security Considerations

​HTTPS Requirement

​Content Security Policy

​Performance Optimization

​Monitoring & Analytics

​Google Analytics

​Plausible Analytics (Privacy-Friendly)

​Troubleshooting

​Updates & Maintenance

​Next Steps

Data Format

Column Mapping

​Support

Build docs developers (and LLMs) love

Overview

Quick Start (Local Development)

Project Structure

Deployment Options

Option 1: GitHub Pages

Option 2: Netlify

Option 3: Vercel

Option 4: AWS S3 + CloudFront

Option 5: Self-Hosted Server

Configuration & Customization

Updating Library Versions

Offline Mode (Optional)

Custom Branding

Security Considerations

HTTPS Requirement

Content Security Policy

Performance Optimization

Monitoring & Analytics

Google Analytics

Plausible Analytics (Privacy-Friendly)

Troubleshooting

Updates & Maintenance

Next Steps

Support