this repo has no description
1# Preloading Example
2
3This context describes the product language and architectural vocabulary for a chaptered learning lab about TanStack preloading, pagination, filtering, and synced local data patterns.
4
5## Language
6
7**Vertical**:
8A product slice organized by what the code does for the user, not by technical category.
9_Avoid_: Code grouping, feature folder, technical layer
10
11**Shared vertical**:
12A vertical for cross-cutting code with a coherent responsibility that is used by more than one product slice.
13_Avoid_: Shared dumping ground, miscellaneous utilities
14
15**Chapter**:
16A learning unit in the reading sequence that pairs exactly one article with exactly one demo.
17_Avoid_: Page, route, layout
18
19**Article**:
20An explanatory content piece paired with a demo inside a chapter.
21_Avoid_: Blog component, copy block
22
23**Demo**:
24An interactive Pokemon listing example paired with an article inside a chapter.
25_Avoid_: Table, widget, example component
26
27**Chapter route**:
28A route module that composes a chapter by wiring its article, demo, route data, and search state.
29_Avoid_: Implementation dumping ground, generated registry entry
30
31**Data**:
32The persistence model and direct database access for Pokemon records.
33_Avoid_: Data layer, server functions, query options, sync routes
34
35**Landing**:
36The home screen that introduces the learning lab and presents entry points into the chapter sequence.
37_Avoid_: Table of contents owner, chapter registry
38
39**Design System**:
40The shared visual foundation for app-wide primitive UI, styling tokens, global CSS, and theme controls.
41_Avoid_: Shared, common components, miscellaneous UI
42
43**Framework adapter**:
44A file kept in a framework-mandated location to register routes, app wiring, or configuration while delegating implementation to verticals where practical.
45_Avoid_: Vertical owner, product slice
46
47## Relationships
48
49- A **Vertical** owns code that changes together for a product concern.
50- A **Shared vertical** may be used by multiple **Verticals** through a small public interface.
51- A **Chapter** contains exactly one **Article** and exactly one **Demo**.
52- The **Article** vertical owns markdown content, markdown rendering, article presentation, and server functions that produce renderable articles.
53- A **Chapter route** is the composition boundary for one **Chapter**.
54- A **Chapter route** may own route-specific integration between TanStack Router loaders, route context, search state, and TanStack Query options.
55- A **Chapter route** should compose **Verticals**, not contain substantial **Article** rendering internals or **Demo** implementation internals.
56- The **Demo** vertical owns the interactive Pokemon listing system, including shared demo UI, server functions, TanStack Query helpers, Electric shape routes, TanStack DB collections, and loading strategy helpers.
57- The **Data** vertical owns schema, relations, seed data, and direct database wrapper queries.
58- The **Demo** vertical consumes the **Data** vertical through direct query interfaces exposed by **Data**.
59- The **Chapters** vertical owns the canonical reading sequence, chapter metadata, table-of-contents data, and chapter navigation.
60- The **Chapters** vertical owns navigation chrome for the chaptered reading experience, including the header, chapter selector, chapter pager, and route navigation helpers.
61- The **Chapters** vertical owns chapter framing and status language, including section headers and status indicators.
62- The **Landing** vertical owns home-page presentation and consumes the **Chapters** vertical for the table of contents.
63- The **Design System** vertical owns primitive UI components, CSS files, styling tokens, utility class merging, and the theme toggle.
64- The **Demo** vertical owns demo cards and panel frames used by the interactive demo surface.
65- Small implementation helpers used only by one vertical belong to that vertical; for example, the lazy component helper belongs to **Demo** while only the demo table uses it.
66- **Framework adapters** may remain in TanStack Start, TanStack Router, or Vite+ default locations even when they register behavior for a vertical.
67- API shape route files are **Framework adapters**; **Demo** owns the Electric collections that depend on those route URLs.
68- Root route, router creation, generated route tree, TanStack Start declarations, and Vite+ configuration are **Framework adapters** unless enough cohesive app-shell implementation emerges to justify a separate vertical.
69- `src/env.ts` remains app-wide runtime configuration and is not owned by **Data** or **Demo**.
70- Product-owned verticals live directly under `src/*` as named top-level directories such as `src/articles`, `src/chapters`, `src/data`, `src/demos`, `src/design-system`, and `src/landing`; framework-mandated files remain in their default locations as **Framework adapters**.
71- Do not introduce a `src/verticals` grouping directory. The earlier `src/verticals/*` plan was reversed because the extra nesting added path noise without improving the domain model.
72- Verticals should not expose app-code barrel files; imports should target the concrete module that owns the thing being imported, while files inside a vertical may use relative imports.
73- Technical categories such as components, server functions, content, utilities, and libraries are not primary ownership boundaries.
74
75## Example dialogue
76
77> **Dev:** "Should this table component stay under components because it renders UI?"
78> **Domain expert:** "No. If it exists to explain a preloading strategy in a demo, it belongs with that **Vertical** unless another **Vertical** consumes it through a public interface."
79
80> **Dev:** "Is the `/basic` route the **Chapter**, or just the layout for one?"
81> **Domain expert:** "It is the **Chapter**: the route is the reading unit that composes one article and one demo."
82
83> **Dev:** "Should markdown rendering utilities live in a generic utils folder?"
84> **Domain expert:** "No. Markdown rendering exists to produce **Article** content, so it belongs to **Article**."
85
86> **Dev:** "Should the route file be empty glue that delegates all chapter composition elsewhere?"
87> **Domain expert:** "No. The **Chapter route** is allowed to compose the **Article** and **Demo**, especially where route data and preloading behavior are part of the lesson."
88
89> **Dev:** "Do Electric shape routes belong to **Data** because they expose tables?"
90> **Domain expert:** "No. They belong to **Demo** because they deliver synced Pokemon listing data to the interactive examples; **Data** owns the persistence model and direct database queries."
91
92> **Dev:** "Should the home page own the chapter list because it renders the table of contents?"
93> **Domain expert:** "No. **Landing** renders the home-page view, but **Chapters** owns the canonical reading sequence."
94
95> **Dev:** "Should the header live in an app-shell vertical?"
96> **Domain expert:** "No. The header is chapter navigation chrome, so it belongs to **Chapters**."
97
98> **Dev:** "Should status dots be part of the demo console?"
99> **Domain expert:** "No. Status indicators are used by **Landing** and chapter navigation, so they belong to **Chapters**."
100
101> **Dev:** "Should `src/components/ui` live in a generic shared folder?"
102> **Domain expert:** "No. Primitive UI, tokens, global styles, and theme controls belong to **Design System**."
103
104> **Dev:** "Should API shape route files move into **Demo** because Electric collections use them?"
105> **Domain expert:** "No. The route files stay in the framework route tree as **Framework adapters**; **Demo** owns the Electric collections that depend on those URLs."
106
107> **Dev:** "Should we create an App Shell vertical for root route and router files?"
108> **Domain expert:** "Not yet. Keep framework-mandated files as **Framework adapters** and extract an app-shell vertical only if cohesive app-shell implementation grows."
109
110> **Dev:** "Should each vertical expose an `index.ts` barrel as its public API?"
111> **Domain expert:** "No. App-code barrels hide dependency shape and can create circular imports; import concrete modules directly."
112
113> **Dev:** "Should verticals live under `src/verticals` so the ownership model is explicit?"
114> **Domain expert:** "No. The ownership model is explicit in the named top-level directories under `src`; `src/verticals` was removed to keep import paths shorter while preserving the same vertical boundaries."
115
116## Flagged ambiguities
117
118- "Shared" can mean either reusable product infrastructure or a dumping ground for unrelated code. Resolved: only use **Shared vertical** for cross-cutting code with a coherent responsibility.