Image URL Mapping System
Relevant source files
The following files were used as context for generating this wiki page:
The Image URL Mapping System is a specialized infrastructure designed to manage the transition of remote image assets to local storage for the "Architecture of Open Source Applications" (AOSA) Korean translation project. Its primary purpose is to ensure that all architectural diagrams, covers, and technical illustrations referenced in the original Markdown files are preserved, localized, and correctly referenced within the new repository structure.
The system facilitates a systematic migration of 395 identified image assets from the original aosabook.org servers to a structured local directory hierarchy. This transition is governed by a master mapping file that links original remote URLs to their corresponding local paths, enabling programmatic updates of document references.
Sources: download_summary.md:3-8, CLAUDE.md:1-5
System Architecture and Components
The system is built around a structured data model and a collection of processing scripts. It organizes images into volumes that mirror the book's organizational structure.
Core Components
- Discovery Engine: Utilizes regular expressions to parse original Markdown files and extract remote image URLs.
- Downloader Scripts: Python and Bash scripts responsible for fetching assets using HTTP requests with specific headers and implementing error handling.
- Mapping Registry: A JSON-based master file (
image_mapping.json) that maintains the relationship between remote sources and local destinations. - Storage Hierarchy: A directory structure that segments images by volume (Volume 1, Volume 2, POSA, 500 Lines) and metadata (Covers).
Sources: download_summary.md:11-53, download_summary.md:65-75
Data Flow for Asset Migration
The following diagram illustrates the flow of data from the initial discovery of a remote image link to its final localized reference in the translated Markdown files.
The diagram shows the sequential process of discovering, downloading, and mapping images.
Sources: download_summary.md:55-63, download_summary.md:83-88
Directory and Storage Structure
The system maintains a strict hierarchical organization to ensure that hundreds of technical diagrams remain manageable. Images are categorized based on the specific volume and chapter they belong to.
Volume Segmentation
| Directory Path | Content Description |
|---|---|
korean_translation/metadata/images/ | Book covers for all four volumes. |
korean_translation/volume1/images/ | Assets for apps like Asterisk, Audacity, and LLVM. |
korean_translation/volume2/images/ | Assets for Git, nginx, and SQLAlchemy. |
korean_translation/posa/images/ | Performance-related diagrams and charts. |
korean_translation/500lines/images/ | Illustrations for the 500 Lines or Less projects. |
Sources: download_summary.md:14-48, CLAUDE.md:11-20
Processing Logic for Path Resolution
When an image is processed, the system generates a local path based on the remote URL structure. This ensures that assets from specific chapters (e.g., "wesnoth" or "asterisk") are grouped together in subdirectories.
This sequence shows how the script interacts with different system components to resolve and store paths.
Sources: download_summary.md:55-63, korean_translation/image_mapping.json
Mapping Logic and Metadata
The central authority of the system is the image_mapping.json file. This registry allows for programmatic replacement of URLs in the translation process.
Registry Schema
The mapping registry tracks every asset using the original URL as the key. This allows the system to identify missing assets, such as the 4 failed downloads discovered during the POSA volume processing (specifically hash-named images from the khmer bioinformatics chapter).
Summary Statistics
| Metric | Value |
|---|---|
| Total Images Discovered | 395 |
| Success Rate | 99% |
| Failed Downloads | 4 (404 Errors) |
| Total Storage Size | ~25.9 MB |
Sources: download_summary.md:3-8, download_summary.md:77-81
Implementation Details
The system was implemented using a combination of Python for data management and Bash for high-speed downloading.
- Download Method: HTTP requests with proper User-Agent headers to avoid blocks.
- Validation: Size checks are performed after download to ensure file integrity.
- Reference Updating: The
image_mapping.jsonfile is designed to be used by automation scripts to replace all remote links in the Markdown files with relative local paths.
Sources: download_summary.md:65-72, download_summary.md:83-88
Conclusion
The Image URL Mapping System provides a robust framework for the preservation of visual technical content in the AOSA translation project. By decoupling the remote URL from the local storage path via a JSON registry, it ensures that the project remains portable, offline-capable, and technically accurate compared to the original source material.