Skip to content

output-structure.md

Latest commit

 

History

History
143 lines (123 loc) · 5.23 KB

output-structure.md

File metadata and controls

143 lines (123 loc) · 5.23 KB
Raw

Output Structure

Audience: Users, Contributors
Scope: Generated file tree and page purposes

Directory Layout

www/
├── index.html                      # AROI leaderboards (main landing page)
├── top500.html                     # Top 500 relays by consensus weight
├── network-health.html             # Network health dashboard
├── search-index.json               # Search data for Cloudflare Pages function
├── robots.txt                      # Crawler policy and sitemap pointer
├── sitemap.xml                     # Canonical-only public URL inventory
│
├── misc/
│   ├── all.html                    # All relays listing
│   ├── all-page-2.html             # Additional clean-route pagination pages
│   ├── aroi-leaderboards.html      # AROI leaderboards (duplicate of index)
│   ├── authorities.html            # Directory authorities monitoring
│   ├── families-by-bandwidth.html  # Families sorted by bandwidth
│   ├── families-by-consensus-weight.html
│   ├── networks-by-bandwidth.html  # AS networks sorted by bandwidth
│   ├── networks-by-consensus-weight.html
│   ├── contacts-by-bandwidth.html  # Operators sorted by bandwidth
│   ├── contacts-by-consensus-weight.html
│   ├── countries-by-bandwidth.html # Countries sorted by bandwidth
│   ├── countries-by-consensus-weight.html
│   ├── platforms-by-bandwidth.html # Platforms sorted by bandwidth
│   └── platforms-by-consensus-weight.html
│
├── relay/
│   └── <fingerprint>/
│       └── index.html              # Individual relay details
│
├── contact/
│   └── <hash>/
│       └── index.html              # Operator profile and relay list
│
├── country/
│   └── <code>/
│       └── index.html              # Country-specific relay listing
│
├── as/
│   └── <number>/
│       └── index.html              # AS-specific relay listing
│
├── family/
│   └── <hash>/
│       └── index.html              # Family relay listing
│
├── platform/
│   └── <name>/
│       └── index.html              # Platform-specific relay listing
│
├── flag/
│   └── <name>/
│       └── index.html              # Flag-specific relay listing
│
├── first_seen/
│   └── <date>/
│       └── index.html              # Relays first seen on date
│
└── static/
    ├── favicon.ico                  # Multi-resolution 1AEO favicon
    ├── *.css                       # Stylesheets
    ├── *.png                       # Country and relay flag images
    └── ...                         # Other static assets

Page Counts (Typical)

Category Approximate Count
Relay pages ~7,000
Contact pages ~3,000
Country pages ~90
AS pages ~1,500
Family pages ~5,000
Platform pages ~50
Flag pages ~10
First seen pages ~4,000
Misc pages ~100
Total ~21,700

Key Files

index.html

Main landing page showing AROI leaderboards with 18 categories of authenticated operator rankings.

top500.html

Top 500 relays sorted by consensus weight fraction. Quick overview of the most influential relays.

network-health.html

10-card dashboard showing network health metrics: relay counts, bandwidth, consensus weight distribution, geographic diversity, platform analysis, and authority health.

search-index.json

JSON file containing relay search data for use with Cloudflare Pages serverless function. Includes nicknames, fingerprints, and family groupings.

robots.txt and sitemap.xml

robots.txt is always generated. With an absolute HTTP(S) --base-url, it points to a sitemap built from the canonical links in the completed HTML tree. Duplicate sort/vanity files collapse to one URL, and noindex pages are omitted. Large inventories automatically use sitemap-N.xml shards.

misc/authorities.html

Directory authority monitoring page with uptime statistics, Z-score analysis, and consensus participation metrics.

URL Patterns

Pattern Example
Relay /relay/9695DFC35FFEB861329B9F1AB04C46397020CE31/
Contact /contact/a1b2c3d4/
Country /country/us/
AS /as/AS13335/
Family /family/e5f6g7h8/
Platform /platform/Linux/
Flag /flag/Exit/

Standalone .html files are published as clean routes: top500.html is linked as /top500, and misc/all.html as /misc/all. Generated HTML files remain on disk for static-host compatibility.

How to Verify

# Generate output
python3 allium/allium.py --out /tmp/test --apis details

# Check structure
find /tmp/test -type f -name "*.html" | wc -l  # Should be ~21,000+
ls /tmp/test/relay/*/index.html | head -5      # Relay pages
ls /tmp/test/contact/*/index.html | head -5    # Contact pages

# Verify key files
test -f /tmp/test/index.html && echo "index.html exists"
test -f /tmp/test/top500.html && echo "top500.html exists"
test -f /tmp/test/search-index.json && echo "search-index.json exists"
test -f /tmp/test/robots.txt && echo "robots.txt exists"