[FEE-1800] Codebase Studies Overview
INFO
Codebase Studies is the FEE category for studying named open-source projects: extracting named patterns from real codebases, anchoring every claim in source, and naming each pattern in a way that lets readers recognize it when they meet it again. The category sits at 1800-1899 and complements FEE-500s (Component Architecture & Design Patterns), which describes the same kinds of patterns abstractly. This overview is also the canonical reference for the category's authoring conventions.
Context
Every other FEE category is technology-topic-organized: HTML, CSS, JavaScript, State Management, etc. Each article describes how a technology or pattern works, with synthetic examples for clarity.
Codebase Studies is the first case-study-organized category. The unit of analysis is a real, named codebase. Each article picks a single named pattern from a single named project, walks through the project's actual source code, and names the pattern in a way that lets the reader recognize it elsewhere.
The intellectual model is the Architecture of Open Source Applications book series and 500 Lines or Less: short, focused tours of one well-engineered piece of software, written so that engineers reading other codebases later can identify the same shapes. The FEE-specific twist is that every article still ends with a transferable handle, so the reader walks away with a named pattern, knows how this project implements it, and knows what to look for when the pattern surfaces again elsewhere.
Visual
| FEE-500s (Component Architecture) | Codebase Studies (1800-1899) | |
|---|---|---|
| Article shape | Pattern in abstract, synthetic example | Pattern as practiced in one named codebase, source as primary anchor |
| Reader's takeaway | Apply the pattern in your own work | Recognize the pattern when you see it in real code |
| Example source | Hand-authored snippet | Verbatim from the project at a pinned commit |
| Cross-link | "See this pattern in action: [Codebase Study]" | "Abstract pattern background: [FEE-500s]" |
A pattern can have articles in both categories simultaneously, with each cross-linking to the other.
Example
Here is the shape of a Codebase Studies article — a one-paragraph excerpt from FEE-1810's Example section, illustrating commit-pinned source citation:
The base class for every renderable object in Three.js,
Object3D, exposes no lifecycle method of its own; disposal is delegated to subclasses that own GPU resources. TheBufferGeometry.dispose()implementation looks like:Source: src/core/BufferGeometry.js:866-871
jsdispose() { this.dispatchEvent({ type: 'dispose' }); }The body is one line: dispatch a
'dispose'event. The actual GPU teardown happens in a listener installed byWebGLRenderer...
The link uses a tag (r172), not main. The line range is included. The code is verbatim. The surrounding prose names what the pattern is and traces it through the code.
Best Practices
- MUST include the
studied_atfrontmatter field on every article in this category. Format:studied_at: "<project> <version> (<YYYY-MM-DD>)". Example:studied_at: "three.js r172 (2025-04-15)". The field records the snapshot the article was written against; without it, articles rot silently as upstream evolves. - MUST use commit-pinned source URLs. Format:
https://github.com/<org>/<repo>/blob/<sha-or-tag>/<path>#L<line>or#L<start>-L<end>. Never link tomain,master, orHEAD. The pinned URL is the contract that the article describes that exact code. - MUST pull code samples verbatim from the source. Eliding unrelated lines with
// ...is fine. Rewriting for readability is not, since that turns "what the project actually does" into "what the article author thinks the project does", which defeats the category's value. - MUST name the pattern in 2-4 words in the topic-specific
##heading, and bold the name on first appearance in the article body so the reader walks away with a handle they can re-spot in other codebases. - SHOULD end the topic-specific section with a "What to look for elsewhere" bullet listing concrete signals (file names, function-name conventions, comment idioms) that let the reader spot the same pattern in unfamiliar code.
- SHOULD cross-link to FEE-500s when the pattern has an abstract counterpart there. The cross-link reads as: "Abstract pattern background: [FEE-50X title]". FEE-500s articles can reciprocate with: "See this pattern in action: [Codebase Study title]".
- MUST NOT use synthetic or pseudocode examples in the Example section. If a real source citation can't be made, the pattern doesn't belong in this category; it belongs in FEE-500s.
Design Thinking
The category's core calibration is that the codebase is the witness, not the subject. A reader of FEE-1810 should walk away knowing about the dispose lifecycle pattern (the named pattern they can apply or spot), with Three.js as the concrete witness that demonstrates it. The article's job is to teach the pattern, with Three.js's source code as the body of evidence.
This calibration carves a sharp line against two failure modes the spec called out during design:
- Over-generalization. If the article forces a "you can apply this anywhere" claim on a pattern that only makes sense in Three.js, the claim is fabrication. Better to scope the recognition: "you'll see this whenever long-running apps own non-GC'd resources" is honest; "every codebase should adopt this" is not.
- Annotated link list. If the article is "here's a tour of Three.js with no transferable takeaway", it's curated reading material rather than an FEE article. The
## <Pattern Name>requirement plus the "What to look for elsewhere" closer keeps every article delivering a recognition handle.
Authoring Conventions
This is the source of truth for category-specific rules. Future articles in 1800-1899 follow these rules in addition to the standard FEE conventions in CLAUDE.md.
studied_atfrontmatter (mandatory). Format:studied_at: "<project> <version> (<YYYY-MM-DD>)". The version can be a release tag (r172,v0.20.0,5.62.10) or a commit short-SHA when no tagged release matches. The date is when the article was written against that version, not the version's release date.- Commit-pinned source URLs. Use
https://github.com/<org>/<repo>/blob/<sha-or-tag>/<path>#L<line>. The<sha-or-tag>MUST match the version instudied_at. - Verbatim code citations. Code blocks pulled from source carry the file path + line range above the block (e.g., Source: src/core/Object3D.js:120-145). Eliding unrelated lines with
// ...is acceptable; rewriting is not. - Pattern name in topic-specific heading. 2-4 words, memorable, in title case. The article body bolds the name on first appearance. Examples: "The Dispose Lifecycle Contract", "The Goroutine + Channel Fanout Model", "The Observer Pattern around QueryCache".
- "What to look for elsewhere" is the closing bullet of the topic-specific section. It names concrete recognition signals: file names ("look for
*.dispose.js"), function-name conventions ("dispose()returningvoid, neverPromise<void>"), comment idioms ("// caller is responsible for cleanup"), or structural shapes ("aWeakMap<Resource, Listener>field on the renderer"). - Cross-link to FEE-500s when the pattern has an abstract counterpart there.
- No-fabrication discipline. Every claim about how the project works links to a specific file/line at the studied commit. If a generalization isn't supported by the source, it doesn't go in the article.
Internal References
- FEE-500 Component Architecture & Design Patterns Overview — the abstract-pattern category that complements this one. Codebase Studies articles cross-link here when their pattern has an abstract counterpart.
References
- Architecture of Open Source Applications (AOSA) — the editorial model this category draws from. AOSA volumes 1-3 plus 500 Lines or Less and The Performance of Open Source Applications are the prior art for short, focused tours of well-engineered software.
- GitHub permalink documentation — the canonical reference for commit-pinned URLs. The "y" keyboard shortcut on a GitHub file view rewrites the URL to a permalink.