awesome-app/CLAUDE.md

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

# 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.