apkviz/CLAUDE.md

CLAUDE.md - Project Context for AI Assistants

This document provides essential context for AI assistants (particularly Claude) to effectively work on the Wolfi APK Dependency Visualizer project.

Project Overview

This is a web application that visualizes package dependencies in the Wolfi Linux distribution (NOT Alpine - this is important!). The app provides advanced analytics to help users understand package relationships, identify critical dependencies, and make informed decisions about their system architecture.

Critical Context

What This Project Does

1. Visualizes Wolfi package dependencies as an interactive force-directed graph
2. Analyzes package criticality - which packages are most depended upon
3. Calculates size impact - total disk space including all dependencies
4. Shows both forward and reverse dependencies - bidirectional analysis
5. Provides system-wide insights via the "Most Critical Packages" dashboard

Key Technical Decisions

• Uses D3.js force simulation for graph layout
• TypeScript for type safety
• Single-page application with no backend required
• APKINDEX file (50MB) is pre-downloaded and served statically
• GitHub Pages deployment via GitHub Actions
• Playwright for automated browser testing

Important Implementation Details

Dependency Analysis Algorithm

The DependencyAnalyzer class provides several key metrics:

• Criticality Score: Direct dependents + (transitive dependents × 0.5)
• Bus Factor: Identifies packages that many others depend on
• Total Size Impact: Recursively calculates package + all dependencies size
• Dependency Depth: Maximum depth of the dependency tree

Visualization Features

1. Three types of dependencies rendered differently:

   • Direct dependencies (solid lines)
   • Transitive dependencies (dashed lines)
   • Reverse dependencies (red lines, showing what depends on this package)

2. Interactive navigation:

   • Click any node to re-center the graph on that package
   • Search box updates to show current package
   • Package details panel shows analytics

3. Performance considerations:

   • Graph only shows dependencies to depth 2 by default
   • Transitive dependencies can be toggled on/off
   • Force simulation stops after stabilization

Testing Infrastructure

• All Playwright test outputs go to playwright-output/ (gitignored)
• Test files are prefixed with test- or demo-
• The quick-debug.js script provides fast screenshot/console capture

Common Tasks

Adding New Analytics

1. Add analysis methods to src/dependency-analyzer.ts
2. Update showPackageStats() in src/index.ts to display results
3. Add appropriate styling in src/styles.css

Modifying the Visualization

1. Core D3 logic is in src/visualization.ts
2. Graph building logic in buildDependencyGraph() and buildTransitiveDependencyGraph()
3. Rendering logic in renderGraph()

Updating Data

npm run fetch-data  # Downloads latest APKINDEX from Wolfi

Deployment

Pushes to main branch automatically trigger GitHub Actions to:

1. Build the project
2. Deploy to GitHub Pages at https://imjasonh.github.io/apkviz/

Known Issues & Gotchas

1. APKINDEX size: The 50MB file triggers GitHub warnings but works fine
2. Base path: Production uses /apkviz/ base path, development uses /
3. Tooltip cleanup: Must properly manage D3 selections to avoid memory leaks
4. Force simulation: Can be CPU intensive with many nodes

Future Enhancement Ideas

1. Security analysis:

   • Highlight packages with known vulnerabilities
   • Show security update paths

2. Performance optimization:

   • Implement virtualization for large graphs
   • Add WebGL rendering option

3. Advanced features:

   • Circular dependency detection
   • Diff between package versions
   • Export dependency graphs as DOT files

Testing Approach

When testing changes:

1. Use npm start for development
2. Run node quick-debug.js screenshot for quick visual checks
3. Use node demo-impressive.js for full feature demonstration
4. Check console for errors with node quick-debug.js console

Code Style Guidelines

1. TypeScript: Use proper types, avoid any when possible
2. D3.js: Chain method calls, use arrow functions
3. CSS: Use CSS classes over inline styles
4. Comments: Focus on WHY not WHAT
5. Git commits: Descriptive messages explaining the change

Important Notes

• This is for Wolfi, NOT Alpine Linux - Never confuse the two
• The visualization should impress friends and shame enemies
• Focus on actionable insights not just pretty graphs
• Performance matters - the app should handle thousands of packages
• The goal is to make dependency management understandable and fun

Contact & Context

This project was created to provide powerful dependency analysis for the Wolfi ecosystem. It should serve as both a practical tool and a showcase of what's possible with modern web technologies and thoughtful data visualization.

When in doubt, prioritize:

1. User experience
2. Actionable insights
3. Performance
4. Visual appeal

Remember: Great tools make complex systems understandable!