# ADR: An App Architecture section in the sidebar

Status: accepted, 2026-09-02, shipped as 1.0.0.28. Steve asked for
everything on the UI to be grouped and well organized, with a new header,
App Architecture, for the code records.

## In plain words

This page moved every document about how the application is built into one sidebar section of its own (App Architecture), placed first. Decisions about how the work is done stay in their own section, so each section holds one kind of thing.

What that is worth: a developer asking how this is built finds the answer in the first section instead of split across two, and the organization's newest writing is no longer hidden at the bottom of a long menu.

## Context

The sidebar grew by accretion. Best Practices ended the day holding
fifteen entries: the practices overview, the records about documentation,
observability, the phone header, the changelog, the sidebar itself, live
samples, cache headers, the palette, the staff review, diagram pages, and
then the three records that walk the code for a new developer. Two
different kinds of thing were filed together: decisions about how the
project is run, and explanations of how the application is built. About
held the README with the data flow and the project structure. All three are
the second kind, filed under a heading that suggests the first.

A visitor looking for "how is this built" had to know that the answer was
split across About and the bottom of Best Practices. That is a grouping
problem. It hid the newest and most useful writing in the repository.

Two documents the README promised at the start of the build were also
still missing: a written architecture (the onion, the wire contract, the
derive-do-not-store principle) and a written style (naming, layering, and
comments that explain why and how, never what), enforced by an
`.editorconfig` rather than by memory. There was no section they belonged
to either.

## Decision

**A section of its own, named for what a visitor is looking for.** App
Architecture sits first in the sidebar, above Hosting, and holds
everything about how the application is built:

- Architecture overview, the new `docs/app-architecture/ARCHITECTURE.md`: the layers and
  which way they point, the seven rules that keep them, a table of where a
  change goes, and what is deliberately absent.
- Coding and commenting style, the new `docs/app-architecture/STYLE.md`: naming, layering,
  the why-and-how comment rule with an example of a comment that earns its
  line, the test rules, and the formatting the `.editorconfig` enforces.
- Data flow and Project structure, moved out of About.
- The three records that walk the code: Program.cs, the React
  configuration, and the tests.

**About holds the README.** It is the introduction to the project, not the
place to file its internals. The resume link stays pinned below the
sections, where it already was.

**Best Practices keeps the decisions about how the work is done**:
versioning, documentation and testing, observability, error handling, the
phone header, the changelog, the sidebar, live samples, cache headers, the
palette, the staff review, diagram pages, and this record. Every entry is
about practice, none about the code's shape.

**`.editorconfig` does the mechanical half.** Indentation, line endings,
using order, `var` usage, braces, unused locals: a tool applies those on
every save and the compiler warns on them, so review spends its attention
on the half a tool cannot check.

## In the code

The one record of every document the sidebar can open, and the section
order (`src/library/sections.ts`):

```ts
architecture: {
  label: 'App Architecture',
  items: [
    { key: 'startHere' },
    { key: 'vscode' },
    { key: 'architecture' },
    { key: 'cleanArchitecture', sub: true },
    { key: 'solid', sub: true },
    { key: 'style', sub: true },
    { key: 'dataflow', sub: true },
    { key: 'projects', sub: true },
  ],
},
```
*Live from [`src/library/sections.ts`](https://github.com/SteveStout/TheYard/blob/1d6b50b/src/library/sections.ts#L88-L100), region `architecture-menu`, read from this build at 1d6b50b.*

```ts
/** Section order, top to bottom: the sidebar and the landing grid both follow it. */
export const MENU_ORDER: readonly MenuVariant[] = SITE_MAP.sections.map((section) => section.menu);
```
*Live from [`src/lib/siteMap.ts`](https://github.com/SteveStout/TheYard/blob/1d6b50b/src/lib/siteMap.ts#L28-L29), region `MENU_ORDER`, read from this build at 1d6b50b.*

The mechanical style rules (`.editorconfig`):

```ini
# The mechanical half of docs/app-architecture/STYLE.md, applied by the editor and the
# compiler instead of by review. Rules a tool cannot check (naming that
# reads well, comments that say why) stay in that document.
root = true

[*]
charset = utf-8
# LF, which is what git has stored for every file here since the first commit.
# .gitattributes is what makes that true in the working tree as well, on every
# machine rather than only on the ones whose core.autocrlf agrees (ADR-028).
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

# The dataset and the published PDFs are written by other tools; leave them alone.
[*.{json,pdf,png,jpg,svg}]
trim_trailing_whitespace = false

[*.md]
# Two trailing spaces are a hard line break in markdown.
trim_trailing_whitespace = false
max_line_length = 100

[*.cs]
indent_size = 4
max_line_length = 120

# Usings inside the namespace-free top of the file, System first, no unused ones.
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false
dotnet_diagnostic.IDE0005.severity = warning

# #region ca1852
# Sealed by default, the practice written up on the Best Practices page
# docs/best-practices/SEALED.md. CA1852 names an internal class that nothing derives from and
# that could be sealed. It is a warning here, and the gate reads any warning as
# red, so the analyzer half of the practice is held by the build rather than by
# review; SealedByDefaultTests holds the public half.
dotnet_diagnostic.CA1852.severity = warning
# #endregion ca1852

# var only where the type is obvious from the right-hand side.
csharp_style_var_for_built_in_types = false:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = false:suggestion

# Expression bodies for one-liners, blocks for anything with a decision in it.
csharp_style_expression_bodied_methods = when_on_single_line:suggestion
csharp_style_expression_bodied_properties = true:suggestion

# Braces always: a single-line if body without them is how a second statement gets lost.
csharp_prefer_braces = true:warning

# Modern C# the codebase already uses.
csharp_style_prefer_primary_constructors = true:suggestion
csharp_style_namespace_declarations = file_scoped:suggestion
csharp_prefer_simple_using_statement = true:suggestion
csharp_style_prefer_pattern_matching = true:suggestion

[*.{ts,tsx,mjs,js}]
indent_size = 2
max_line_length = 100
quote_type = single

[*.{yml,yaml}]
indent_size = 2

[*.css]
indent_size = 2
```
*Live from [`.editorconfig`](https://github.com/SteveStout/TheYard/blob/1d6b50b/.editorconfig#L1-L71), region `*`, read from this build at 1d6b50b.*

## Consequences

- The sidebar's first section now answers the question most visitors
  arrive with, and each section holds one kind of thing.
- Three end-to-end tests name the sections; all three were updated, and
  two of them assert the new section renders in the rail and in the phone
  drawer.
- The rail is taller by one section. At 1024 pixels and up it scrolls
  inside itself, which it already did; on a phone the drawer scrolls.
- Moving a record between sections does not change its address. The slug
  in `DocumentationCatalog.cs` is the identity; the menu is presentation only, and
  the cross-check test still holds the two lists together (ADR: The staff
  review).

## Where it sits

No ring: regrouping the sidebar is a documentation decision whose only code is data in src/library/sections.ts, so the onion and SOLID do not apply to it.

## Files

- [`src/library/sections.ts`](https://github.com/SteveStout/TheYard/blob/main/src/library/sections.ts): the sections and their order.
- [`src/library/documents.ts`](https://github.com/SteveStout/TheYard/blob/main/src/library/documents.ts): the document record.
- [`api/TheYard.Api/DocumentationCatalog.cs`](https://github.com/SteveStout/TheYard/blob/main/api/TheYard.Api/DocumentationCatalog.cs): the two new slugs.
- [`docs/app-architecture/ARCHITECTURE.md`](https://github.com/SteveStout/TheYard/blob/main/docs/app-architecture/ARCHITECTURE.md) and [`docs/app-architecture/STYLE.md`](https://github.com/SteveStout/TheYard/blob/main/docs/app-architecture/STYLE.md): the two documents this section was made for.
- [`.editorconfig`](https://github.com/SteveStout/TheYard/blob/main/.editorconfig): the mechanical rules.
- [`tests/e2e/sidebar.spec.ts`](https://github.com/SteveStout/TheYard/blob/main/tests/e2e/sidebar.spec.ts), [`tests/e2e/mobile.spec.ts`](https://github.com/SteveStout/TheYard/blob/main/tests/e2e/mobile.spec.ts), [`tests/e2e/smoke.spec.ts`](https://github.com/SteveStout/TheYard/blob/main/tests/e2e/smoke.spec.ts): the section names and the two new pages, checked in a browser.
- [`docs/decisions/ADR-013-sidebar.md`](https://github.com/SteveStout/TheYard/blob/main/docs/decisions/ADR-013-sidebar.md): the sidebar itself, which this record only regroups.

## Addendum, 2026-09-29: UI architecture, from App Architecture

The look has an architecture page of its own, UI architecture in the Style section: the four design token files, the base and panel sheets, the component sheets, the site map and the document layout, each reading only the layers below it. App Architecture stays about the API, the stores and the data, and links to it rather than repeating it.