From 51779c6cd992aa1e5cf534f3ddb47826759ea903 Mon Sep 17 00:00:00 2001 From: valknarness Date: Sun, 26 Oct 2025 15:25:13 +0100 Subject: [PATCH] docs: readme --- CLAUDE.md | 176 ++++++++++++++ README.md | 670 +++++++++++++++++++++++++++--------------------------- 2 files changed, 516 insertions(+), 330 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..14be877 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,176 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**Awesome Web** is a Next.js 15 web application for browsing and searching "awesome lists" from GitHub. It features full-text search powered by SQLite FTS5, personal list management with a rich markdown editor, and automated database builds via GitHub Actions. + +**Tech Stack:** +- Next.js 15 (App Router) + TypeScript +- Tailwind CSS 4 with custom theme (purple/pink/gold gradients) +- shadcn/ui components (New York style) +- SQLite3 with better-sqlite3 + FTS5 for full-text search +- Zustand for state management +- TipTap for WYSIWYG markdown editing +- Node.js 22+ required + +## Common Development Commands + +```bash +# Development server +npm run dev + +# Production build +npm run build +npm start + +# Type checking +npm run type-check + +# Linting +npm run lint +``` + +## Architecture Overview + +### Database Layer (`lib/db.ts`) + +Central database abstraction for SQLite operations: +- **Connection Management**: Singleton pattern with WAL mode for concurrency +- **Database Path**: `$AWESOME_DB_PATH` or `~/.awesome/awesome.db` (from awesome CLI) +- **Core Functions**: + - `searchRepositories()` - FTS5 full-text search with faceted filtering (language, stars, category) + - `getAwesomeLists()` - Hierarchical list of awesome lists + - `getRepositoryWithReadme()` - Fetch repository details with README content + - `getCategories()` / `getLanguages()` - Facet data for filters + - `getStats()` - Database statistics for homepage + +**Search Architecture**: Uses SQLite FTS5 with `readmes_fts` virtual table. Queries are parsed into FTS format (`"term1"* OR "term2"*`) and support sorting by relevance, stars, or recent activity. + +### Personal List Management (`lib/personal-list-store.ts`) + +Zustand store with localStorage persistence for user-curated lists: +- **Items Management**: CRUD operations for saved repositories/resources +- **Markdown Sync**: Bidirectional sync between structured items and markdown representation +- **Editor Integration**: State for TipTap editor (view modes: editor/preview/split) +- **Export/Import**: JSON export and markdown generation + +### API Routes (`app/api/*`) + +- `/api/search` - Repository search endpoint (wraps `lib/db.ts`) +- `/api/repositories/[id]` - Single repository details +- `/api/lists` - User personal lists CRUD +- `/api/lists/[id]` - Single list operations +- `/api/stats` - Database statistics +- `/api/db-version` - Database version for cache invalidation +- `/api/webhook` - GitHub Actions webhook for database update notifications + +### Component Structure + +**Layout Components** (`components/layout/`): +- `app-header.tsx` - Main navigation with command menu trigger +- `app-sidebar.tsx` - Tree navigation for awesome lists hierarchy +- `command-menu.tsx` - Global search command palette (Cmd+K) + +**Personal List Components** (`components/personal-list/`): +- `personal-list-editor.tsx` - TipTap-based markdown editor with rich formatting +- `push-to-list-button.tsx` - "Add to list" button for repositories +- `sliding-panel.tsx` - Side panel for personal list management +- `personal-list-items.tsx` - Structured view of saved items + +**README Viewer** (`components/readme/`): +- `readme-viewer.tsx` - Markdown rendering with syntax highlighting (marked + highlight.js) +- `readme-header.tsx` - Repository metadata header (stars, language, actions) + +**UI Components** (`components/ui/`): +- shadcn/ui components (New York style) +- Custom `kbd.tsx` for keyboard shortcut displays + +### Theme System + +Custom Tailwind theme matching the awesome CLI branding: +- **Primary Colors**: `--awesome-purple: #DA22FF`, `--awesome-pink: #FF69B4`, `--awesome-gold: #FFD700` +- **Gradients**: Utility classes for purple-to-gold gradients (buttons, text, backgrounds) +- **Dark Mode**: Next-themes integration with system preference detection +- **Typography**: Tailwind typography plugin for markdown rendering + +Configuration in `tailwind.config.ts` and `app/globals.css`. + +### Database Build System + +**Automated Builds** (`.github/workflows/db.yml`): +- Runs every 6 hours or manual trigger +- Two modes: + 1. **Download mode** (default, ~5 min): Downloads pre-built DB from `valknarness/awesome` repository + 2. **Build mode** (~1-2 hours): Clones awesome CLI and runs full indexing +- Artifacts retained for 90 days with metadata JSON + +**Build Script** (`scripts/build-db.js`): +- Uses GitHub CLI to download artifacts or spawns awesome CLI indexer +- Generates `db-metadata.json` with build stats +- Fallback to local build if download fails + +### Page Routes + +- `/` - Landing page with statistics and featured lists +- `/browse` - Browse all awesome lists +- `/search` - Search interface with faceted filtering +- `/list/[id]` - Single awesome list view with repositories +- `/repository/[id]` - Repository detail with README +- `/readme/[owner]/[repo]` - Direct README viewer +- `/my-list` - Personal list editor +- `/legal`, `/disclaimer`, `/imprint` - Legal pages + +## Important Development Notes + +### Database Schema Expectations + +The SQLite database must have these tables: +- `awesome_lists` - List metadata (id, name, url, description, category, stars, parent_id, level) +- `repositories` - Repository data (id, awesome_list_id, name, url, description, stars, language, topics) +- `readmes` - README content (id, repository_id, raw_content) +- `readmes_fts` - FTS5 virtual table for full-text search + +### Path Aliases + +- `@/` maps to project root +- `@/components` - React components +- `@/lib` - Utilities and shared logic +- `@/hooks` - Custom React hooks +- `@/app` - Next.js app router pages + +### Service Worker + +`public/worker.js` implements background polling for database updates: +- Polls `/api/db-version` with exponential backoff +- Notifies client on version change for cache invalidation +- Smart polling reduces when page inactive + +### Node.js Version + +Requires Node.js 22+ (specified in `package.json` engines). Use pnpm for package management. + +### shadcn/ui Components + +Components use "New York" style variant. When adding new shadcn components, ensure they match the custom theme colors defined in `components.json` and `app/globals.css`. + +### Adding New Search Filters + +When extending search functionality: +1. Update `SearchOptions` interface in `lib/db.ts` +2. Add filter logic to SQL query in `searchRepositories()` +3. Update API route in `app/api/search/route.ts` +4. Add UI controls in search page components + +### TipTap Editor Extensions + +The personal list editor uses these TipTap extensions: +- Starter Kit (basic formatting) +- Code Block Lowlight (syntax highlighting) +- Table extensions (table support) +- Task List/Item (checklist support) +- Character Count (word count display) +- Typography (smart quotes, em dashes) + +When modifying the editor, ensure all extensions are properly configured in `personal-list-editor.tsx`. diff --git a/README.md b/README.md index 6359359..0cc035f 100644 --- a/README.md +++ b/README.md @@ -1,339 +1,349 @@ -# ✨ AWESOME WEB - Next-Level Ground-Breaking AAA Webapp ✨ +
-> A stunning, feature-rich web application for exploring and discovering awesome lists from GitHub +# 🕶️ ✨ AWESOME WEB ✨ 🕶️ +### *The Most Funkadelic, Cosmically-Enhanced, Star-Powered GitHub Explorer in the Known Universe!* -**🚀 Built with:** Next.js 18 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA +![Funky Awesome](https://i.gifer.com/3SBW.gif) -## 🎨 Design Philosophy +> 🎤 *"Yeah baby! We got that COSMIC SLOP of awesome lists, sprinkled with STARDUST and served on a MOTHERSHIP of Next.js goodness! Slide into the funkiest GitHub explorer this side of the galaxy, ya dig?"* +> +> **— Bootsy Collins, Minister of Funk & Chief Awesome Officer** -This webapp perfectly matches the **beautiful purple/pink/gold theme** from the Awesome CLI: -- 💜 **Awesome Purple**: `#DA22FF` -- 💗 **Awesome Pink**: `#FF69B4` -- 💛 **Awesome Gold**: `#FFD700` +[![Funk Level](https://img.shields.io/badge/Funk%20Level-MAXIMUM-DA22FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDJjLS41NSAwLTEgLjQ1LTEgMXY4SDljLS41NSAwLTEgLjQ1LTEgMXYxMGMwIC41NS40NSAxIDEgMWgxMGMuNTUgMCAxLS40NSAxLTF2LTEwYzAtLjU1LS40NS0xLTEtMWgtMlYzYzAtLjU1LS40NS0xLTEtMWgtNHoiIGZpbGw9IiNGRkQ3MDAiLz48L3N2Zz4=)](https://github.com) +[![Platform Boots](https://img.shields.io/badge/Platform%20Boots-6%20Inches-FF69B4?style=for-the-badge)](https://github.com) +[![Star Power](https://img.shields.io/badge/⭐%20Star%20Power-∞-FFD700?style=for-the-badge)](https://github.com) +[![Groove Factor](https://img.shields.io/badge/Groove-UNSTOPPABLE-9733EE?style=for-the-badge)](https://github.com) -## 🌟 Features Implemented - -### ✅ Core Infrastructure - -1. **Next.js 18 Setup** - - App router with TypeScript - - Optimized build configuration - - PWA support ready - - Image optimization - -2. **Tailwind CSS 4 Custom Theme** - - Matching CLI color scheme - - Custom gradient utilities - - Beautiful button styles - - Smooth animations - - Custom scrollbar - - Typography plugin - -3. **GitHub Actions Workflow** - - Two build modes: - - **Download Mode**: Fast (~5 min) - downloads pre-built database from awesome CLI repo - - **Build Mode**: Slow (~1-2 hours) - builds locally using awesome CLI indexer - - Runs every 6 hours (download mode by default) - - Manual trigger with mode selection - - Configurable source repository - - Artifact upload (90-day retention) - - Metadata generation with build stats - - Fallback to local build if download fails - -4. **Web Worker System** - - Smart polling with exponential backoff - - Cache invalidation - - Client notification system - - Efficient resource usage - - Background updates - -5. **API Routes** - - `/api/db-version` - Database version endpoint - - `/api/webhook` - GitHub Actions webhook handler - - Signature verification - - Metadata management - -### 🎯 Architecture - -``` -awesome-web/ -├── .github/workflows/ -│ └── db.yml ✅ Automated DB building -├── app/ -│ ├── layout.tsx ✅ Root layout with theme -│ ├── globals.css ✅ Custom awesome styles -│ ├── api/ -│ │ ├── db-version/ ✅ Version checking -│ │ └── webhook/ ✅ Update notifications -│ ├── page.tsx 🔨 Landing hero (to build) -│ ├── list/[id]/ 🔨 List index page -│ ├── readme/[...]/ 🔨 README viewer -│ ├── legal/ 🔨 Legal pages -│ └── not-found.tsx 🔨 404 with easter egg -├── components/ -│ ├── ui/ 🔨 shadcn components -│ ├── layout/ -│ │ ├── sidebar.tsx 🔨 Tree navigation -│ │ └── command-menu.tsx🔨 Search command -│ ├── search/ -│ │ ├── facets.tsx 🔨 Search facets -│ │ └── filters.tsx 🔨 Advanced filters -│ └── providers/ -│ └── worker-provider.tsx 🔨 Worker integration -├── public/ -│ ├── worker.js ✅ Service worker -│ ├── manifest.json ✅ PWA manifest -│ └── icons/ 🔨 Generate from logo -├── scripts/ -│ └── build-db.js ✅ Database builder (download/build modes) -├── tailwind.config.ts ✅ Custom theme -└── next.config.js ✅ PWA & optimization -``` - -## 🚀 Getting Started - -### Installation - -```bash -cd /home/valknar/Projects/node.js/awesome-web -npm install -``` - -### Development - -```bash -npm run dev -``` - -Open [http://localhost:3000](http://localhost:3000) - -### Build - -```bash -npm run build -npm start -``` - -## 📋 Next Steps to Complete - -### 1. Landing Page 🔨 -- [ ] Hero section with gradient buttons -- [ ] Feature showcase -- [ ] Statistics display -- [ ] Call-to-action sections - -### 2. Command Search (kbd bindings) 🔨 -- [ ] shadcn Command component -- [ ] Full-text search integration -- [ ] Search facets (language, stars, topics) -- [ ] Sorting options -- [ ] Live preview -- [ ] Pagination - -### 3. Sidebar Navigation 🔨 -- [ ] Tree structure of awesome lists -- [ ] Live search/filter -- [ ] Collapsible categories -- [ ] Active state indicators - -### 4. README Viewer 🔨 -- [ ] State-of-the-art markdown rendering -- [ ] Syntax highlighting -- [ ] Sticky action header -- [ ] Share functionality -- [ ] Star button -- [ ] Original link - -### 5. UI Components 🔨 -- [ ] Install shadcn/ui components -- [ ] Create custom components -- [ ] Toast notifications -- [ ] Loading states -- [ ] Error boundaries - -### 6. Logo & Assets 🔨 -- [ ] Adapt sindresorhus/awesome logo -- [ ] Generate favicon -- [ ] Create PWA icons (all sizes) -- [ ] Header logo -- [ ] OG image - -### 7. Legal Pages 🔨 -- [ ] Legal page -- [ ] Disclaimer -- [ ] Imprint -- [ ] Beautiful styling - -### 8. 404 Page with Easter Egg 🔨 -- [ ] Custom 404 design -- [ ] AWESOME easter egg -- [ ] Interactive elements -- [ ] Animated graphics - -### 9. Database Integration 🔨 -- [ ] SQLite connection -- [ ] Search implementation -- [ ] Faceted search -- [ ] Results pagination -- [ ] Error handling - -### 10. Worker Provider 🔨 -- [ ] React context for worker -- [ ] Update notifications -- [ ] Cache management -- [ ] Toast integration - -## 🎨 Theme Showcase - -### Colors -```css -/* Primary Purple */ ---awesome-purple: #DA22FF; ---awesome-purple-light: #E855FF; ---awesome-purple-dark: #9733EE; - -/* Secondary Pink */ ---awesome-pink: #FF69B4; ---awesome-pink-light: #FFB6D9; ---awesome-pink-dark: #FF1493; - -/* Accent Gold */ ---awesome-gold: #FFD700; ---awesome-gold-light: #FFE44D; ---awesome-gold-dark: #FFC700; -``` - -### Gradients -```css -/* Main Gradient */ -background: linear-gradient(135deg, #DA22FF 0%, #9733EE 50%, #FFD700 100%); - -/* Pink Gradient */ -background: linear-gradient(135deg, #FF1493 0%, #DA22FF 50%, #9733EE 100%); - -/* Gold Gradient */ -background: linear-gradient(135deg, #FFD700 0%, #FF69B4 50%, #FF1493 100%); -``` - -### Components -- **Buttons**: Gradient background with hover lift -- **Cards**: Border glow on hover -- **Text**: Gradient text utility classes -- **Scrollbar**: Gradient thumb -- **Focus**: Purple ring -- **Selection**: Purple highlight - -## 🔧 Technical Stack - -### Frontend -- **Next.js 18** - React framework -- **TypeScript** - Type safety -- **Tailwind CSS 4** - Utility-first CSS -- **shadcn/ui** - Component library -- **Radix UI** - Headless components -- **cmdk** - Command palette -- **Lucide** - Icons - -### Backend -- **SQLite3** - Database -- **better-sqlite3** - Node.js driver -- **FTS5** - Full-text search -- **Node.js 22+** - Runtime - -### Build & Deploy -- **GitHub Actions** - CI/CD -- **Web Workers** - Background sync -- **PWA** - Progressive web app -- **Service Worker** - Offline support - -## 🎯 Key Features to Implement - -### Search Excellence -- ⚡ Lightning-fast FTS5 -- 🎨 Faceted filtering -- 🔤 Syntax highlighting -- 📄 Live preview -- 🔀 Multiple sort options -- 📊 Result statistics - -### Smart Updates -- 🔄 Auto-detect new DB versions -- 📢 User notifications -- ♻️ Cache invalidation -- 🎯 Background sync -- ⚡ Zero downtime updates - -### Beautiful UX -- 🎨 Gorgeous gradients -- ✨ Smooth animations -- 📱 Responsive design -- ♿ Accessibility -- 🌗 Dark mode -- ⌨️ Keyboard shortcuts - -## 📝 Development Notes - -### shadcn/ui Installation -```bash -npx shadcn-ui@latest init -npx shadcn-ui@latest add button dialog dropdown-menu toast command scroll-area -``` - -### Environment Variables -```env -# .env.local -WEBHOOK_SECRET=your-secret-here -DB_URL=https://your-host.com/awesome.db -GITHUB_TOKEN=your-github-token -``` - -### GitHub Secrets -- `WEBHOOK_SECRET` - For webhook verification -- `WEBHOOK_URL` - Your Next.js webhook endpoint - -## 🎉 What Makes This AWESOME - -1. **Perfect Theme Match** - Exact CLI color scheme -2. **Smart Updates** - Worker polls, notifies, updates seamlessly -3. **GitHub Integration** - Automated builds every 6 hours -4. **PWA Ready** - Install as app on any device -5. **Next-Level Search** - Facets, filters, live preview -6. **Beautiful Design** - State-of-the-art UI/UX -7. **Intelligent** - Smart polling, cache management -8. **Complete** - End-to-end solution - -## 📖 Documentation - -- [GitHub Workflow](.github/workflows/db.yml) - Database building -- [Web Worker](public/worker.js) - Background sync -- [API Routes](app/api/) - Webhook & version checking -- [Tailwind Config](tailwind.config.ts) - Custom theme - -## 🚀 Deployment - -### Vercel (Recommended) -```bash -vercel deploy -``` - -### Environment Setup -1. Add environment variables -2. Configure GitHub webhook -3. Set up database hosting -4. Generate PWA icons - -## 💡 Future Enhancements - -- [ ] Advanced analytics -- [ ] User accounts -- [ ] Saved searches -- [ ] Export functionality -- [ ] Mobile app -- [ ] Browser extension -- [ ] API for developers +**🚀 Powered By The Funk:** Next.js 15 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA Magic --- -**Built with 💜💗💛 and maximum awesomeness!** +
-*This is a GROUND-BREAKING, NEXT-LEVEL, AAA webapp that perfectly complements the awesome CLI!* +## 🎸 What's This Funkadelic Trip All About? + +Yo, check it! This ain't your grandma's GitHub list browser (no disrespect to grandma). This is a **FULL-BLOWN PSYCHEDELIC EXPERIENCE** for exploring awesome lists from GitHub. We're talkin' purple, pink, and GOLD, baby! We're talkin' FULL-TEXT SEARCH powered by SQLite FTS5 running at the SPEED OF FUNK! We're talkin' a personal list editor so smooth it'll make you wanna BOOGIE! + +### 🌟 The Cosmic Feature List (Funkometer: 11/10) + +#### 🎯 **The P-Funk Database Experience** +- **FTS5 Full-Text Search** - Search faster than Bootsy's bass licks! ⚡ +- **Faceted Filtering** - Filter by language, stars, topics - smooth as silk! 🎨 +- **Hierarchical Navigation** - Browse awesome lists like you're navigating the Mothership 🚀 +- **Personal List Curation** - Save your faves with our WYSIWYG markdown editor (powered by TipTap) ✍️ +- **Real-time Updates** - Web workers polling for fresh data every 6 hours! 🔄 +- **PWA Ready** - Install it on ANY device and take the funk MOBILE! 📱 + +#### 🕶️ **The Aesthetic Funk** +- **Purple/Pink/Gold Theme** - Colors so fly, they'll make you CRY! 💜💗💛 + - `#DA22FF` - That FUNKY Purple + - `#FF69B4` - That SASSY Pink + - `#FFD700` - That COSMIC Gold +- **Gradient Everything** - Buttons, text, backgrounds - all sliding through the rainbow! 🌈 +- **Smooth Animations** - Transitions smoother than a James Brown slide! ✨ +- **Dark Mode** - For those late-night funk sessions! 🌙 +- **Custom Scrollbar** - Even the scrollbar got STYLE! 📜 + +#### 🤖 **The Technical Groove** + +**Frontend Funk:** +- Next.js 15 (App Router) + TypeScript - Modern as tomorrow! +- Tailwind CSS 4 - Utility-first FUNK! +- shadcn/ui Components - Beautiful AND accessible! +- Radix UI - Headless but not heartless! +- Motion/Framer Motion - Animations that MOVE you! +- Lucide Icons - Icons with SOUL! + +**Backend Bass Line:** +- SQLite3 + better-sqlite3 - Database with GROOVE! +- FTS5 Full-Text Search - Finding stuff at LIGHT SPEED! +- Node.js 22+ - The latest and GREATEST! +- Zustand State Management - State so fresh it squeaks! + +**DevOps Drumbeat:** +- GitHub Actions - Automated builds every 6 hours! +- Web Workers - Background sync like a BACKBEAT! +- PWA Support - Offline? NO PROBLEM! +- Docker Ready - Container that CONTAINS the funk! + +--- + +## 🎤 Getting Your Funk On (Installation) + +Alright, space cadets! Let's get this MOTHERSHIP launched! + +### 🛸 Prerequisites + +You're gonna need: +- **Node.js 22+** (The funk requires modern tech!) +- **pnpm** (Package manager with STYLE!) +- **Better-sqlite3** (For that database GROOVE!) + +### 🚀 Launch Sequence + +```bash +# Clone this funkadelic masterpiece +git clone https://github.com/yourusername/awesome-web.git +cd awesome-web + +# Install the cosmic dependencies +pnpm install + +# Fire up the development server (Mothership: ACTIVATED!) +pnpm dev + +# Open your browser to http://localhost:3000 +# Put on your sunglasses +# Prepare for MAXIMUM FUNK! 🕶️ +``` + +### 🏗️ Building for Production + +```bash +# Build that funky fresh production bundle +pnpm build + +# Launch the production server +pnpm start + +# Deploy to Vercel/wherever and SPREAD THE FUNK! 🌍 +``` + +--- + +## 🎨 The Funkadelic Architecture + +``` +awesome-web/ 🏛️ THE MOTHERSHIP +├── 🎸 app/ +│ ├── layout.tsx 💜 Root layout with COSMIC theme +│ ├── globals.css 🎨 Where the MAGIC happens +│ ├── page.tsx 🏠 Landing page of FUNK +│ ├── search/ 🔍 Search with STYLE +│ ├── browse/ 📚 Browse with GROOVE +│ ├── my-list/ ✨ Personal list MAGIC +│ └── api/ 🚀 API routes for DATA +│ ├── search/ 💫 Full-text search endpoint +│ ├── repositories/ 📦 Repository details +│ ├── stats/ 📊 Database statistics +│ └── db-version/ 🔄 Version checking +│ +├── 🎵 components/ +│ ├── layout/ +│ │ ├── app-header.tsx 🎩 Header with ATTITUDE +│ │ ├── app-sidebar.tsx 📂 Sidebar with SOUL +│ │ └── command-menu.tsx ⌨️ Cmd+K for COSMIC search +│ ├── personal-list/ +│ │ ├── personal-list-editor.tsx ✍️ WYSIWYG editor +│ │ ├── push-to-list-button.tsx 💾 Save with STYLE +│ │ └── sliding-panel.tsx 📱 Panel that SLIDES +│ ├── readme/ +│ │ ├── readme-viewer.tsx 📖 Markdown with FLAVOR +│ │ └── readme-header.tsx 🎯 Header with STARS +│ └── ui/ 🎨 shadcn components with FUNK +│ +├── 🎹 lib/ +│ ├── db.ts 💾 Database GROOVE +│ ├── personal-list-store.ts 🗂️ Zustand state MAGIC +│ ├── themes.ts 🎨 Theme POWER +│ └── utils.ts 🔧 Utility FUNK +│ +├── 🌟 public/ +│ ├── worker.js 🤖 Service worker MAGIC +│ ├── manifest.json 📱 PWA manifest +│ └── icons/ ✨ Funkadelic icons +│ +├── 🎬 scripts/ +│ └── build-db.js 🏗️ Database builder (2 modes!) +│ +└── 🚀 .github/workflows/ + └── db.yml ⚙️ Automated builds every 6 hours +``` + +--- + +## 🎯 Key Features (The Funk Breakdown) + +### 🔍 **Search Like You Mean It!** +Our FTS5-powered search is FASTER than a cheetah on roller skates! Search by: +- **Keywords** - Find ANYTHING in milliseconds! +- **Language** - JavaScript? Python? We got 'em all! +- **Stars** - Filter by popularity (but everything's a STAR here!) +- **Category** - Organize that KNOWLEDGE! + +### 📝 **Personal List Editor - Your Own Awesome Creation!** +Built with TipTap, this editor got MORE extensions than Parliament-Funkadelic: +- ✨ Rich text formatting (bold, italic, strikethrough) +- 📋 Tables, task lists, code blocks +- 🎨 Syntax highlighting for code +- 📊 Character count +- 💾 Auto-save to localStorage (your funk is SAFE!) +- 📤 Export to markdown (SHARE the funk!) + +### 🔄 **Smart Updates - Set It and Forget It!** +Our Web Worker is like a ROBOT BASSIST - always keeping the rhythm: +- Polls database version every 6 hours +- Notifies you when new data drops +- Cache invalidation (OLD data? GONE!) +- Exponential backoff (SMART and efficient!) + +### 🎨 **Theme System - Purple Rain Meets Cosmic Slop!** + +```css +/* The Funkadelic Palette */ +--awesome-purple: #DA22FF; /* 💜 Primary FUNK */ +--awesome-pink: #FF69B4; /* 💗 Secondary GROOVE */ +--awesome-gold: #FFD700; /* 💛 Accent SHINE */ + +/* Gradients that'll BLOW YOUR MIND */ +background: linear-gradient(135deg, + #DA22FF 0%, /* Purple PASSION */ + #9733EE 50%, /* Violet VIBES */ + #FFD700 100% /* Golden GLORY */ +); +``` + +--- + +## 🏗️ Automated Database Building (The GitHub Actions GROOVE) + +We got TWO build modes, baby! + +### ⚡ **Download Mode** (Default - Fast Like Lightning!) +- Downloads pre-built database from `valknarness/awesome` repo +- Takes ~5 minutes (TIME is money, honey!) +- Runs every 6 hours automatically +- Fallback to build mode if download fails (SMART!) + +### 🔨 **Build Mode** (Slow But Thorough!) +- Clones awesome CLI and runs FULL indexing +- Takes 1-2 hours (PATIENCE is a virtue!) +- Manual trigger only (for the CONTROL FREAKS!) +- Generates fresh database with ALL the data + +**Trigger it manually:** +```bash +# Via GitHub Actions UI +# Select "Build mode" and hit "Run workflow" +# Then sit back and let the FUNK flow! 🎸 +``` + +--- + +## 🚀 Deployment (Spread the Funk Worldwide!) + +### Deploy to Vercel (Recommended!) + +```bash +# Install Vercel CLI +pnpm i -g vercel + +# Deploy! +vercel deploy + +# BOOM! Your funk is LIVE! 🌍 +``` + +### Environment Variables (Keep 'em Secret, Keep 'em Safe!) + +```env +# .env.local +AWESOME_DB_PATH=/path/to/awesome.db +WEBHOOK_SECRET=your-secret-here +GITHUB_TOKEN=your-github-token +``` + +--- + +## 🎯 What Makes This COSMICALLY AWESOME? + +1. **🎨 Perfect Theme Match** - Colors straight from the awesome CLI! HARMONIOUS! +2. **⚡ Lightning Search** - FTS5 search faster than a meteor! ZOOM! +3. **💾 Smart Caching** - Web workers keeping things FRESH! +4. **🤖 Automation** - GitHub Actions building databases while you SLEEP! +5. **📱 PWA Ready** - Install it ANYWHERE! Desktop! Mobile! TOASTER! +6. **♿ Accessible** - Keyboard shortcuts, ARIA labels, semantic HTML - EVERYONE gets the funk! +7. **🌗 Dark Mode** - Light mode for DAY, dark mode for NIGHT! +8. **✨ Smooth UX** - Animations smoother than BUTTER on a hot skillet! + +--- + +## 🎵 Development Notes (For the Funkateers!) + +### Adding shadcn/ui Components + +```bash +npx shadcn@latest add button dialog dropdown-menu toast command scroll-area +# Add ALL the components! MORE is MORE! +``` + +### Database Schema + +The SQLite database vibes with these tables: +- `awesome_lists` - List metadata (ALL the lists!) +- `repositories` - Repository data (ALL the repos!) +- `readmes` - README content (ALL the docs!) +- `readmes_fts` - FTS5 virtual table (SEARCH POWER!) + +### Path Aliases (Keep It Clean!) + +- `@/` - Project root (HOME base!) +- `@/components` - UI components (BUILDING blocks!) +- `@/lib` - Utilities (TOOL box!) +- `@/app` - Next.js pages (THE routes!) + +--- + +## 🌟 Future Enhancements (The Cosmic Roadmap!) + +- [ ] 🎮 **Gamification** - Earn badges for exploring lists! COLLECT 'EM ALL! +- [ ] 👥 **User Accounts** - Save preferences in the CLOUD! +- [ ] 📊 **Analytics Dashboard** - See what's TRENDING! +- [ ] 🔔 **Push Notifications** - Get alerted when lists UPDATE! +- [ ] 🌐 **Internationalization** - FUNK in every language! +- [ ] 📱 **Mobile App** - React Native version (THE REMIX!) +- [ ] 🔌 **Browser Extension** - Search from ANYWHERE! +- [ ] 🤖 **AI Recommendations** - "You might also like..." with INTELLIGENCE! + +--- + +## 📜 License + +MIT License - Free as a bird, baby! Use it, share it, FUNK IT UP! + +--- + +
+ +## ⭐ CREDITS ⭐ + +### 🎸 The One and Only FUNK Himself 🎸 + + + +**Built with 💜💗💛 by funkateers worldwide** + +*"Free your mind and your code will follow!"* + +--- + +### Special Shoutout To: + +🎤 **Bootsy Collins** - For inspiring the COSMIC vision +🌟 **George Clinton** - For the MOTHERSHIP connection +🎸 **Parliament-Funkadelic** - For the GROOVE foundation +⭐ **sindresorhus/awesome** - For the original awesome lists +💜 **The Open Source Community** - For keeping the FUNK alive + +--- + +### 🕶️ One Nation Under A Groove 🕶️ + +*If you dig this funkadelic masterpiece, drop us a ⭐ STAR ⭐ on GitHub!* +*Let's spread the FUNK across the galaxy, one awesome list at a time!* + +![Footer Funk](https://media.giphy.com/media/3o7btXJQd87m5kVfSo/giphy.gif) + +**P-FUNK NEVER DIES!** 🎸✨🚀 + +