Site Navigation and Indexes
Relevant source files
The following files were used as context for generating this wiki page:
The "Site Navigation and Indexes" system serves as the structural backbone of "The Architecture of Open Source Applications" (AOSA) series. It organizes complex technical content across multiple volumes, providing users with a clear entry point to various architectural case studies. The primary goal is to allow developers to study the structures of existing programs and learn from technical critiques written by experienced practitioners.
The system is architected as a static site with a hierarchical directory structure. It utilizes a central index and specialized metadata to guide users through four distinct volumes: Volume 1, Volume 2, Performance (POSA), and 500 Lines or Less. Each volume contains an introduction, specific chapter files, and, in some cases, a bibliography, ensuring comprehensive coverage of open-source software design patterns.
Sources: metadata/index.html.md:8-16, CLAUDE.md:15-30
Repository Directory Structure
The repository is organized into specific directories that separate the book volumes and metadata. This segmentation ensures that content remains self-contained and manageable.
The diagram shows the high-level folder structure and key navigation files within the AOSA repository.
Volume Organization
The content is categorized by the nature of the architectural problems addressed:
| Directory | Content Description | Chapter Pattern |
|---|---|---|
volume1/ | 25 chapters on general applications (Asterisk, LLVM, etc.) | {number}_{name}.html.md |
volume2/ | 24 chapters including Git, nginx, and PyPy | {number}_{name}.html.md |
posa/ | 12 chapters focused on performance aspects | {number}_{name}.html.md |
500lines/ | 22 chapters implementing systems in <500 lines | {number}_{name}.html.md |
metadata/ | Site-wide metadata, index, and licensing | Specialized filenames |
Sources: CLAUDE.md:15-38
Navigation Logic and File Conventions
Navigation is facilitated by strict file naming conventions and cross-referencing. The primary index file (metadata/index.html.md) serves as the Global Table of Contents, linking to each volume's introduction and individual chapters.
Global Index (Table of Contents)
The metadata/index.html.md file (and its Korean translation equivalent) acts as the central hub. It provides:
- Volume Overviews: High-level summaries of each book volume.
- Chapter Lists: Tabular data containing chapter numbers, titles, and author attributions.
- Cross-References: Relative and absolute URLs to chapters and bibliographies.
Sources: metadata/index.html.md:31-255, korean_translation/metadata/index.html.md:1-200
Chapter Naming and Sequence
Chapters follow a two-digit prefixing system (00-99) to ensure sequential sorting and easy navigation:
- 00: Always reserved for the Introduction (e.g.,
00_introduction.html.md). - 01-25: Specific case studies.
- 99: Reserved for the Bibliography (e.g.,
99_bibliography.html.md).
Sources: CLAUDE.md:31-41
Metadata and Frequently Asked Questions
Beyond basic navigation, the site includes metadata components that handle licensing, purchase information, and FAQs.
FAQ Navigation Flow
The metadata/faq.html.md file uses an internal anchor-based navigation system to allow users to quickly jump to specific questions regarding the book's availability, licensing (Creative Commons Attribution 3.0), and contribution guidelines.
Navigation flow within the FAQ metadata file.
Sources: metadata/faq.html.md:1-125
Contribution and Translation Access
Navigation to "how to contribute" is integrated into the index and individual introductions. It provides direct mailto links to coordinators for new translations or chapter submissions.
Sources: metadata/index.html.md:237-248, volume1/00_introduction.html.md:387-393
Conclusion
The navigation and indexing system of the AOSA project is designed for discoverability and educational flow. By utilizing a consistent naming convention and a centralized metadata hub, the project ensures that developers can easily transition from broad introductions to specific deep-dives into software architecture. The inclusion of Korean translations within the korean_translation/ directory further extends this navigation structure to a global audience.
Sources: CLAUDE.md:42-50, korean_translation/metadata/index.html.md:1-10