Repository Structure & Conventions

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• metadata/index.html.md
• metadata/faq.html.md
• volume1/00_introduction.html.md
• volume2/00_introduction.html.md
• posa/00_introduction.html.md
• 500lines/00_introduction.html.md

This repository hosts the Markdown-formatted Korean translation of "The Architecture of Open Source Applications" (AOSA) book series. The project serves as a technical documentation hub, detailing the structural designs and architectural decisions of various open-source projects across four distinct volumes. The primary goal of the repository structure is to provide a standardized, sequential, and navigable format for educational content derived from real-world software architectures.

Sources: CLAUDE.md:1-7, metadata/index.html.md:8-16

## Core Directory Organization

The repository is organized into five primary top-level directories, four representing the main book volumes and one containing shared metadata. Each volume directory acts as a self-contained unit for the specific book's content.

Directory	Content Description	Chapter Count
volume1/	Chapters covering projects like Asterisk, Audacity, and LLVM.	25 Chapters + Intro + Bib
volume2/	Chapters covering Git, nginx, SQLAlchemy, and others.	24 Chapters + Intro + Bib
posa/	Performance-focused chapters (Performance of Open Source Applications).	12 Chapters + Intro
500lines/	Systems implemented in 500 lines or less.	22 Chapters + Intro
metadata/	Shared book metadata including index, FAQ, and licensing.	6 Files

Sources: CLAUDE.md:11-28, CLAUDE.md:38-42

### Hierarchical Data Flow

The repository uses a centralized index located in the metadata/ directory to facilitate navigation across all volumes. Each volume maintains its own internal sequence, starting with an introduction.

The diagram shows how metadata/index.html.md serves as the entry point for cross-volume navigation.
Sources: CLAUDE.md:31-36, metadata/index.html.md:20-205

## File Naming and Formatting Conventions

The repository strictly follows a numeric-prefix naming convention to maintain the reading order specified by the original book series.

### Chapter Naming Pattern

Files within the volume directories follow the pattern: {chapter-number}_{chapter-name}.html.md.

• Chapter Number: A two-digit number. 00 is reserved for introductions, 01-25 for standard chapters, and 99 for bibliographies.
• Chapter Name: A kebab-case descriptive title corresponding to the project name (e.g., wesnoth, mercurial).

Sources: CLAUDE.md:31-36

### Special File Conventions

Specific files serve as structural anchors within each directory:

• Introductions: Every content directory contains 00_introduction.html.md.
• Bibliographies: Volume 1 and Volume 2 contain 99_bibliography.html.md.
• Image References: The posa/ directory contains four specific image reference files for performance diagrams.

Sources: CLAUDE.md:37-43

## Content Specifications

Each Markdown file represents a converted HTML document and must adhere to a specific internal organization to ensure consistency across the series.

### Internal Document Structure

Each chapter file is required to contain the following components:

1. Author Attributions: Clearly defined at the beginning of the file.
2. Technical Content: Markdown-formatted text including project-specific architectural discussions.
3. External References: Relative URLs linking to aosabook.org for external context.
4. Visual Aids: References to architectural diagrams and code examples (though these are often referenced rather than embedded).

Sources: CLAUDE.md:46-50, CLAUDE.md:57-60

### License and Metadata Files

The metadata/ directory contains critical project information that governs the reuse of the repository's content.

File	Purpose
faq.html.md	Answers regarding e-book formats, translations, and licensing (CC-A).
index.html.md	The main Table of Contents for all volumes and author listings.
license.html.md	Details of the Creative Commons Attribution 3.0 Unported license.
CLAUDE.md	Operational guide for AI-assisted development in the repository.

Sources: CLAUDE.md:39-43, metadata/faq.html.md:1-125

## Contribution and Extension Logic

The repository follows an open-source contribution model where volunteers handle error reporting, translations, and architectural descriptions.

This diagram illustrates the workflow for adding new content or translations to the repository.
Sources: metadata/index.html.md:214-222, metadata/faq.html.md:126-150

## Summary

Repository structure and conventions are designed to mirror the professional architecture of the software they document. By utilizing a strict numeric prefixing system, volume-based categorization, and centralized metadata, the project maintains a clear pedagogical path for readers. The reliance on Markdown and specific naming patterns ensures the content remains portable, searchable, and consistent with the original AOSA publication standards.