Handling Missing Images (404s)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
In the context of "The Architecture of Open Source Applications" (AOSA) project, "Handling Missing Images (404s)" refers to the systematic process of auditing, downloading, and documenting image assets used across the book volumes. Given that the project involves a massive migration and translation effort (such as the Korean translation project), maintaining the integrity of visual assets—which include architectural diagrams, software screenshots, and covers—is critical.
The process involves identifying remote image URLs within Markdown files, attempting automated downloads, and identifying failures where server assets are no longer available (resulting in HTTP 404 errors). This documentation outlines the methodology for identifying missing assets and the resulting directory structure used to localize the remaining valid images.
Sources: download_summary.md:1-5, CLAUDE.md:1-10
Asset Audit and Download Process
The project utilized a series of Python and Bash scripts to extract image URLs from Markdown source files via regular expressions and systematic folder traversal. The goal was to reach a high success rate while identifying specific gaps in the content repository.
Download Workflow
The following diagram illustrates the automated workflow used to reconcile image assets:
The system scanned across four main volumes and metadata directories, successfully processing 395 images with a 99% success rate.
Sources: download_summary.md:6-10, download_summary.md:105-115
Identified 404 Failures
Audit logs revealed that 4 specific images could not be retrieved. These images were specifically linked to the Performance of Open Source Applications (POSA) volume, specifically the "Khmer" bioinformatics chapter.
| Volume | Chapter | Status | File Identifier (Hash-named) |
|---|---|---|---|
| POSA | Khmer | 404 Error | 27125ed60f3aefb748b861550ffb777fff6f470b... |
| POSA | Khmer | 404 Error | 43588c9979407fddf368f36dc1f7b27b379f04f1... |
| POSA | Khmer | 404 Error | 082b32652d6b4a8f56a948a266585c101aae08a1... |
| POSA | Khmer | 404 Error | 2fa8337313c608500df30a465aaf5332fd2eded9... |
These assets appear to be hash-named images that are no longer present on the aosabook.org server, indicating they may have been temporary assets or were removed during server migrations.
Sources: download_summary.md:85-95
Asset Categorization and Storage
To mitigate future 404 risks and facilitate local translation, successfully downloaded images were organized into a hierarchical directory structure matching the book's architecture.
Directory Structure Organization
The localized assets are stored under korean_translation/ with subdirectories for each volume:
- metadata/images/: Contains book covers (e.g.,
cover1.jpg,posa-cover.png). - volume1/images/: Subfolders for specific chapters like
asterisk/,audacity/, andwesnoth/. - volume2/images/: Subfolders for chapters like
git/,nginx/, andyocto/. - posa/images/: Performance-related diagrams.
- 500lines/images/: Subfolders for project-specific images like
spreadsheet/.
Sources: download_summary.md:15-60, CLAUDE.md:13-30
Mapping and Resolution
A master image_mapping.json file was generated to map the original remote URLs to the new local paths. This mapping serves as the authoritative source for updating Markdown references and ensuring that no further 404 errors occur during offline viewing or localized builds.
{
"https://aosabook.org/static/cover1.jpg": "metadata/images/cover1.jpg",
"https://aosabook.org/static/wesnoth/architecture.png": "volume1/images/wesnoth/architecture.png"
}
Sources: download_summary.md:70-80, volume1/25_wesnoth.html.md:100-110
Conclusion
The project successfully localized 391 out of 395 image assets. By identifying the specific 404 errors within the POSA volume, developers are able to target manual reconstruction or find alternative visual aids for the Khmer bioinformatics chapter. The transition from remote URLs to a structured local repository prevents future asset loss and ensures the long-term viability of the documentation.
Sources: download_summary.md:100-105, volume2/06_git.html.md:250-260