Permaweb Glossary Search

A modern, lightning-fast search application for the Permaweb Glossary built with Astro and featuring dual-mode search capabilities. This application provides both Glossary search for specific terms and Documentation search for comprehensive Permaweb ecosystem documentation.

✨ Features

🔍 Dual-Mode Search

Glossary Mode: Fast search across curated Permaweb terms and definitions
Documentation Mode: Comprehensive search across Arweave, AO, AR.IO, and HyperBEAM documentation
Seamless Mode Switching: One-click toggle between search modes with URL persistence

⚡ Performance & UX

Lightning Fast: Documentation search loads 15x faster using pre-extracted content
Fuzzy Search: Find relevant content even with typos or partial matches
Keyboard Navigation: Full arrow key support and keyboard shortcuts
Mobile Responsive: Optimized for all device sizes
Theme Support: Light/dark theme with smooth transitions

🏗️ Modern Architecture

Modular Design: Clean, extensible architecture with pluggable search providers
Astro Framework: Server-side rendering with optimal performance
Client-Side Search: No server dependencies for search functionality
Progressive Enhancement: Works with or without JavaScript

🌐 Integration Ready

Embeddable: Easy iframe integration for other Permaweb sites
JSON API: ~~Programmatic access at /json?q=query&mode=docs~~ (Temporarily disabled - see docs/DECENTRALIZED_SEARCH_ANALYSIS.md)
URL Parameters: Deep linking and shareable search results
Color Customization: Theme integration for different websites

🚀 Quick Start

Prerequisites

Node.js ≥16.0.0 or Bun ≥1.0.0
Modern web browser (Chrome, Firefox, Safari, Edge)

Local Development

Clone and install:

git clone <repository-url>
cd permaweb-glossary
bun install

Start development server:
```
bun dev
```
Navigate to http://localhost:4321
With synchronized data (for local testing with fresh documentation):
```
bun run sync:dev
```

Building for Production

bun run build

The built files will be in the dist/ directory.

📁 Project Architecture

Modern Modular Structure

permaweb-glossary/
├── src/
│   ├── scripts/                    # Modular JavaScript architecture
│   │   ├── search-manager.js       # Central search orchestrator
│   │   ├── search-state.js         # Reactive state management
│   │   ├── search-provider.js      # Base provider interface
│   │   ├── basic-search-provider.js   # Glossary search implementation
│   │   ├── enhanced-search-provider.js # Documentation search implementation
│   │   ├── search-config.js        # Search configuration
│   │   ├── permaweb-config.js      # Permaweb integration settings
│   │   └── main.js                 # Application initialization
│   ├── pages/                      # Astro pages
│   │   ├── index.astro             # Main search interface
│   │   ├── define.astro            # Term definition page
│   │   └── unused/                 # Disabled components
│   │       └── json.astro          # JSON API endpoint (disabled)
│   ├── layouts/
│   │   └── Layout.astro            # Base layout component
│   └── styles/
│       └── style.css               # Modern CSS with CSS custom properties
├── public/
│   ├── data/
│   │   └── glossary.json           # Glossary database
│   ├── docs-index.json             # Documentation search index
│   └── service-worker.js           # Progressive Web App support
├── scripts/                        # Deployment and utility scripts
│   ├── deploy-production.sh        # Production deployment to Arweave
│   ├── deploy-preview.sh           # Preview deployment to Vercel
│   └── sync-permaweb-llm-data.js   # Local data synchronization
└── docs/                           # Project documentation
    ├── BUGS.md                     # Issue tracking
    └── ROADMAP.md                  # Development roadmap

Search Provider Architecture

The application uses a modular search provider system:

SearchManager: Orchestrates search providers and manages application state
SearchState: Reactive state management with subscriber pattern
BasicSearchProvider: Handles glossary search with enhanced relevance scoring
EnhancedSearchProvider: Handles documentation search with LLM integration

🔧 How It Works

Search System

Initialization: SearchManager registers and initializes search providers
Mode Switching: Users can toggle between Glossary and Documentation modes
Query Processing: Each provider implements its own search algorithm:
- Basic: FlexSearch with fuzzy matching and relevance scoring
- Enhanced: Pre-extracted content from permaweb-llm-fuel with full-text search
Result Display: Unified result rendering with consistent styling

Performance Optimization

Pre-extracted Content: Documentation search uses preprocessed content files
Lazy Loading: Search providers initialize on-demand
Efficient Caching: Smart caching strategies for both content and search indices
Minimal Network Requests: Reduced from 100+ to 5 requests for documentation search

🎮 Usage

Basic Search

Type in the search box to find glossary terms
Use arrow keys to navigate results
Press Enter to select a result
Click the title to toggle between Glossary and Documentation modes

URL Parameters

?q=search+term - Set initial search query
?mode=enhanced - Start in Documentation mode
?mode=basic - Start in Glossary mode (default)

JSON API

~~Access programmatic search at /json:~~ (Temporarily disabled)

# Search glossary (DISABLED)
# curl "https://your-domain.com/json?q=arweave&mode=glossary"

# Search documentation (DISABLED)
# curl "https://your-domain.com/json?q=ao+computer&mode=docs"

Note: The JSON API endpoint has been temporarily disabled due to technical limitations with non-browser environments. See docs/DECENTRALIZED_SEARCH_ANALYSIS.md for details on potential future decentralized search implementation using AO processes.

🎨 Customization

Embedding in Other Sites

<!-- Basic embed -->
<iframe 
  src="https://glossary_tiny4vr.permagate.io/" 
  width="100%" 
  height="600px" 
  frameborder="0">
</iframe>

<!-- With custom colors -->
<iframe 
  src="https://glossary_tiny4vr.permagate.io/?bg-color=%23121212&text-color=%23e0e0e0&link-color=%238ab4f8" 
  width="100%" 
  height="600px" 
  frameborder="0">
</iframe>

Available Color Parameters

Parameter	Description	Default
`bg-color`	Background color	`#ffffff`
`text-color`	Main text color	`#111111`
`link-color`	Link and accent color	`#0066cc`
`hover-color`	Hover state color	`#004499`
`border-color`	Border color	`#e0e0e0`
`input-bg`	Search input background	`#ffffff`
`result-bg`	Result item background	`#f8f9fa`
`result-hover`	Result hover background	`#e9ecef`

Note: Colors must be URL-encoded (e.g., # becomes %23).

Adding New Glossary Terms

Edit public/data/glossary.json:

{
  "term": "New Term",
  "definition": "Definition of the new term...",
  "category": "Category Name",
  "related": ["Related Term 1", "Related Term 2"],
  "aliases": ["alias1", "alias2"],
  "docs": ["https://documentation-link.com"]
}

🚀 Deployment

Production Deployment (Arweave)

bun run deploy

Choose option to create PR or deploy directly to main branch.

Preview Deployment (Vercel)

bun run deploy:preview

Fast preview deployment for testing changes.

Manual Vercel Deployment

bun run deploy:vercel        # Production
bun run deploy:vercel:preview # Preview

🔗 Integration with Permaweb LLM Fuel

The documentation search leverages the permaweb-llm-fuel project for enhanced performance:

15x Faster Loading: Pre-extracted content eliminates individual page fetching
Comprehensive Coverage: Includes Arweave, AO, AR.IO, HyperBEAM, and more
Automatic Updates: Content updates automatically when source documentation changes
Offline Capable: Optional local sync for development

Local Development with Sync

# Ensure permaweb-llm-fuel is built first
cd ../permaweb-llm-fuel && bun run build

# Sync fresh data to glossary
cd ../permaweb-glossary
bun run sync        # Sync data only
bun run sync:dev    # Sync + start dev server

📊 Performance Metrics

Metric	Before	After	Improvement
Documentation Load Time	30-45s	2-3s	15x faster
Network Requests	100+ pages	5 files	20x fewer
Initial Bundle Size	-	Optimized	Minimal
Search Response Time	-	<200ms	Lightning fast

🛠️ Development

Available Scripts

bun dev                    # Start development server
bun run build             # Build for production  
bun run preview           # Preview production build
bun run sync              # Sync LLM data locally
bun run sync:dev          # Sync + start dev server
bun run deploy            # Interactive deployment
bun run deploy:preview    # Fast preview deployment

Contributing

The modular architecture makes contributing easier:

Search Providers: Extend SearchProvider to add new search capabilities
UI Components: Enhance the Astro components and styles
Performance: Optimize loading and search algorithms
Testing: Add comprehensive test coverage

Architecture Benefits

Extensible: Easy to add new search providers or data sources
Maintainable: Clear separation of concerns with modular components
Performant: Lazy loading and optimized bundling
Testable: Isolated components with clear interfaces

🆘 Troubleshooting

Common Issues

Documentation search not working:
- Check browser console for network errors
- Verify permaweb-llm-fuel URLs are accessible
- Try the fallback mode (should auto-fallback to glossary)
Slow loading:
- Ensure using pre-extracted content mode
- Check network timeout settings
- Verify CDN/gateway accessibility
Search results missing:
- Check if data files are properly loaded
- Verify glossary.json format
- Look for JavaScript errors in console

Development Issues

Run bun run sync to get fresh local data
Ensure relative paths are correct in sync script
Verify permaweb-llm-fuel is built before syncing

📋 Browser Support

Chrome 88+
Firefox 85+
Safari 14+
Edge 88+

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our ROADMAP for current priorities and BUGS for known issues.

🌐 Experience the future of permanent web documentation search at glossary_tiny4vr.permagate.io

Name		Name	Last commit message	Last commit date
.astro		.astro
.github/workflows		.github/workflows
docs		docs
public		public
scripts		scripts
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
INTEGRATION.md		INTEGRATION.md
README.md		README.md
astro.config.mjs		astro.config.mjs
bun.lock		bun.lock
package.json		package.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation