Skip to content

Commit ad2a987

Browse files
StevenTCramerStevenTCramer
authored
Merge pull request #238 from TimeWarpEngineering/StevenT.Cramer/2025-07-06/chore_ADRs
Complete directory naming convention analysis and fixes
2 parents 89cc1e6 + b60e519 commit ad2a987

36 files changed

+567
-56
lines changed

‎TimeWarp.Architecture/Kanban/Done/029_Create-Directory-Naming-Convention-Analysis-Report/Components-Directory-Structure-Analysis.md

Lines changed: 325 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
# Components Directory Structure Analysis
2+
3+
**Date**: 2025-01-07
4+
**Analysis Scope**: TimeWarp.Architecture/Source/ContainerApps/Web/Web.Spa/Components/
5+
**Purpose**: Comprehensive analysis of naming conventions in the Components directory
6+
7+
## Complete Directory Structure with Files
8+
9+
```
10+
Components/
11+
├── Base/
12+
│ ├── Abstractions/
13+
│ │ ├── IAttributeComponent.cs
14+
│ │ └── IParentComponent.cs
15+
│ ├── DisplayComponent.cs
16+
│ ├── EditMode.cs
17+
│ └── ParentComponent.cs
18+
├── Composites/
19+
│ ├── AuthorizedFluentNavLink.razor
20+
│ └── TimeWarpPage/
21+
│ ├── LeftPane/
22+
│ │ ├── LeftPane.razor
23+
│ │ ├── LeftPane_Footer.razor
24+
│ │ ├── LeftPane_Header.razor
25+
│ │ └── LeftPane_Main.razor
26+
│ ├── RightPane/
27+
│ │ ├── RightPane.razor
28+
│ │ ├── RightPane_Footer.razor
29+
│ │ ├── RightPane_Header.razor
30+
│ │ └── RightPane_Main/
31+
│ │ ├── AsidePane/
32+
│ │ │ ├── AsidePane.razor
33+
│ │ │ ├── AsidePane_Footer.razor
34+
│ │ │ ├── AsidePane_Header.razor
35+
│ │ │ └── AsidePane_Main.razor
36+
│ │ ├── PagePane/
37+
│ │ │ ├── PagePane.razor
38+
│ │ │ ├── PagePane_Footer.razor
39+
│ │ │ ├── PagePane_Header.razor
40+
│ │ │ └── PagePane_Main.razor
41+
│ │ └── RightPane_Main.razor
42+
│ ├── TimeWarpPage.md
43+
│ ├── TimeWarpPage.png
44+
│ ├── TimeWarpPage.razor
45+
│ └── TimeWarpPageSubComponentBase.cs
46+
├── Elements/
47+
│ ├── Button.razor
48+
│ ├── Button.razor.cs
49+
│ ├── HyperLink.razor
50+
│ ├── HyperLink.razor.cs
51+
│ ├── SimpleAlert.razor
52+
│ ├── Text.razor
53+
│ ├── TimeWarpNavLink.razor
54+
│ └── TimeWarpNavUrl.razor
55+
├── Forms/
56+
│ ├── FormContainer.razor
57+
│ └── InputSelectNumber.cs
58+
├── Interfaces/
59+
│ ├── INavigableComponent.cs
60+
│ └── IStaticRoute.cs
61+
├── Layouts/
62+
│ ├── FluentUIRequiredFeatures.razor
63+
│ └── MainLayout.razor
64+
├── Pages/
65+
│ ├── NotificationBanner.razor
66+
│ ├── SideNavigation.razor
67+
│ ├── SideNavigation.razor.cs
68+
│ ├── SideNavigationLink.razor
69+
│ ├── SideNavigationLink.razor.cs
70+
│ ├── SiteFooter.razor
71+
│ ├── SitePage/
72+
│ │ ├── LeftPane_Footer.razor
73+
│ │ ├── LeftPane_Header.razor
74+
│ │ ├── LeftPane_Main.razor
75+
│ │ ├── RightPane_Footer.razor
76+
│ │ ├── RightPane_Header.razor
77+
│ │ ├── SitePage.md
78+
│ │ └── SitePage.razor
79+
│ ├── Stacked/
80+
│ │ ├── Overview.md
81+
│ │ ├── StackedPage.razor
82+
│ │ └── StackedPage.razor.cs
83+
│ └── _Imports.razor
84+
├── Services/
85+
│ └── LinkHelper.cs
86+
├── Overview.md
87+
└── Routes.razor
88+
```
89+
90+
## 🔍 Critical Findings
91+
92+
### **1. Two Completely Different Component Organization Patterns**
93+
94+
#### **Pattern A: TimeWarpPage (Subdirectory Approach)**
95+
```
96+
TimeWarpPage/
97+
├── LeftPane/ # Subdirectory
98+
│ ├── LeftPane.razor # Main component
99+
│ ├── LeftPane_Footer.razor # Sub-components with underscores
100+
│ ├── LeftPane_Header.razor
101+
│ └── LeftPane_Main.razor
102+
└── RightPane/ # Another subdirectory
103+
├── RightPane.razor
104+
├── RightPane_Footer.razor
105+
└── RightPane_Main/ # ❌ NESTED subdirectory with underscore!
106+
```
107+
108+
#### **Pattern B: SitePage (Flat Approach)**
109+
```
110+
SitePage/
111+
├── SitePage.razor # Main component
112+
├── LeftPane_Footer.razor # Sub-components, NO subdirectories
113+
├── LeftPane_Header.razor
114+
├── LeftPane_Main.razor
115+
├── RightPane_Footer.razor
116+
└── RightPane_Header.razor
117+
```
118+
119+
**Key Insight**: SitePage uses underscores **INSTEAD OF** subdirectories!
120+
121+
### **2. The Underscore Pattern Is Actually Consistent!**
122+
123+
The underscore pattern represents **component hierarchy**:
124+
- TimeWarpPage: Uses subdirectories AND underscores (double hierarchy)
125+
- SitePage: Uses underscores INSTEAD of subdirectories (single hierarchy)
126+
- Other components: Simple single-file components (no hierarchy needed)
127+
128+
### **3. Directory Naming Pattern Revealed**
129+
130+
The `RightPane_Main/` directory initially appeared inconsistent, but it's actually **logical**:
131+
132+
```
133+
RightPane/
134+
├── RightPane_Footer.razor # Simple component (file)
135+
├── RightPane_Header.razor # Simple component (file)
136+
└── RightPane_Main/ # Complex component (directory)
137+
├── AsidePane/ # Contains sub-components
138+
├── PagePane/ # Contains sub-components
139+
└── RightPane_Main.razor # The main component file
140+
```
141+
142+
**The underscore pattern extends to directories when they represent component parts that contain sub-components!**
143+
144+
This maintains naming consistency with sibling components while indicating it's a container.
145+
146+
### **4. Component Organization Logic Revealed**
147+
148+
Now the file structure shows clear **organizational tiers**:
149+
150+
#### **Tier 1: Simple Components** (Individual files)
151+
- `Elements/Button.razor`
152+
- `Elements/Text.razor`
153+
- `Pages/NotificationBanner.razor`
154+
155+
#### **Tier 2: Complex Components** (Flat with underscores)
156+
- `SitePage/LeftPane_Header.razor`
157+
- `SitePage/RightPane_Footer.razor`
158+
159+
#### **Tier 3: Mega Components** (Nested subdirectories + underscores)
160+
- `TimeWarpPage/LeftPane/LeftPane_Header.razor`
161+
- `TimeWarpPage/RightPane/RightPane_Main/AsidePane/AsidePane_Footer.razor`
162+
163+
### **5. Misplaced Components Discovery**
164+
165+
The complete structure reveals **AuthorizedFluentNavLink.razor** as an anomaly:
166+
- Single file in `Composites/` (not in subfolder)
167+
- Should probably be in `Elements/` with other navigation components
168+
169+
## 📊 Statistical Analysis
170+
171+
### Directory Organization
172+
| Category | Count | Purpose |
173+
|----------|-------|---------|
174+
| Base | 1 | Component infrastructure |
175+
| Composites | 1 | Complex multi-part components |
176+
| Elements | 1 | Basic UI elements |
177+
| Forms | 1 | Form-related components |
178+
| Interfaces | 1 | Component contracts |
179+
| Layouts | 1 | Page layouts |
180+
| Pages | 3 | Page components & templates |
181+
| Services | 1 | Component services |
182+
183+
### File Type Distribution
184+
| Type | Count | Examples |
185+
|------|-------|----------|
186+
| `.razor` files | 35 | Components |
187+
| `.razor.cs` files | 3 | Code-behind files |
188+
| `.cs` files | 11 | Classes/Interfaces |
189+
| `.md` files | 3 | Documentation |
190+
191+
## 🚨 Major Inconsistencies
192+
193+
### **1. The Underscore Problem**
194+
195+
**Inconsistent Usage:**
196+
- **TimeWarpPage**: Uses underscores in both directory (`RightPane_Main/`) AND files
197+
- **SitePage**: Uses underscores ONLY in files, NOT directories
198+
- **Other components**: No underscores at all
199+
200+
**Example Comparison:**
201+
```
202+
TimeWarpPage/RightPane/RightPane_Main/ ❌ Underscore in directory
203+
SitePage/LeftPane_Header.razor ✅ Only in files
204+
Elements/Button.razor ✅ No underscores
205+
```
206+
207+
### **2. Page Organization Confusion**
208+
209+
**Why are these in different places?**
210+
- `Components/Composites/TimeWarpPage/` - A page template
211+
- `Components/Pages/SitePage/` - Also a page template
212+
- `Components/Pages/Stacked/StackedPage.razor` - Another page template
213+
214+
**Logic unclear**: What determines if a page goes in Composites vs Pages?
215+
216+
### **3. Services Directory Anomaly**
217+
218+
`Components/Services/` contains only `LinkHelper.cs`
219+
- Why is a service in the Components directory?
220+
- Should be in a separate Services directory at a higher level?
221+
222+
## 📋 Naming Pattern Analysis
223+
224+
### **Underscore Pattern Deep Dive**
225+
226+
The underscore pattern appears to represent **component composition hierarchy**:
227+
228+
```
229+
ComponentName_SubPart.razor
230+
```
231+
232+
**Where Used:**
233+
1. TimeWarpPage (17 instances)
234+
2. SitePage (5 instances)
235+
236+
**Pattern Benefits:**
237+
- Visual hierarchy clarity
238+
- Self-documenting structure
239+
- Avoids naming conflicts
240+
241+
**Pattern Problems:**
242+
- Inconsistent application
243+
- Mixed with directory naming (`RightPane_Main/`)
244+
- Not documented as standard
245+
246+
### **Code-Behind Pattern**
247+
248+
Only 3 components use code-behind:
249+
- `Button.razor.cs`
250+
- `HyperLink.razor.cs`
251+
- `SideNavigation.razor.cs`
252+
253+
**Question**: Why only these? What's the criteria?
254+
255+
## 🎯 Recommendations
256+
257+
### **Immediate Actions**
258+
259+
1. **Move Misplaced Component**
260+
```
261+
Composites/AuthorizedFluentNavLink.razor → Elements/AuthorizedFluentNavLink.razor
262+
```
263+
264+
2. **Document the Sophisticated Pattern**
265+
- The underscore pattern extends to directories when they represent component containers
266+
- Create ADR documenting the component hierarchy naming system
267+
- Document when to use directories vs. underscores vs. both
268+
269+
### **Strategic Decisions Needed**
270+
271+
1. **Embrace the Organizational Tiers**
272+
```
273+
Tier 1: Simple (single file) → Elements/, Forms/, etc.
274+
Tier 2: Complex (flat + underscores) → SitePage pattern
275+
Tier 3: Mega (nested + underscores) → TimeWarpPage pattern
276+
```
277+
278+
2. **Clarify Composites vs Pages**
279+
- Composites: Reusable complex components (TimeWarpPage)
280+
- Pages: Specific page implementations (SitePage for site-specific layout)
281+
- This distinction actually makes sense!
282+
283+
3. **Standardize Code-Behind Usage**
284+
- Document criteria for when to use `.razor.cs`
285+
- Currently: Components with complex logic (Button, HyperLink, Navigation)
286+
287+
## 🔄 Suggested Reorganization
288+
289+
```
290+
Components/
291+
├── Base/
292+
│ └── Abstractions/
293+
├── Elements/ # Simple components
294+
├── Forms/ # Form components
295+
├── Composites/ # Complex multi-part components (NOT pages)
296+
├── Pages/ # ALL page templates
297+
│ ├── Templates/ # Page templates (TimeWarpPage, SitePage)
298+
│ │ ├── TimeWarpPage/
299+
│ │ ├── SitePage/
300+
│ │ └── StackedPage/
301+
│ └── Shared/ # Shared page components
302+
├── Layouts/ # Layout components
303+
└── Interfaces/ # Component contracts
304+
```
305+
306+
## Summary
307+
308+
The Components directory actually shows **intelligent component organization** once the complete file structure is visible:
309+
310+
### ✅ **What's Working Well**
311+
- **Three-tier complexity system** (Simple → Complex → Mega components)
312+
- **Logical underscore pattern** for component hierarchy
313+
- **Clear separation** between reusable (Composites) and specific (Pages) components
314+
- **Consistent Pascal case** for directories (with one exception)
315+
316+
### ❌ **Issues to Fix**
317+
1. **Misplaced component**: `AuthorizedFluentNavLink.razor` should be in Elements/
318+
2. **Missing documentation** of the sophisticated component organization patterns
319+
320+
### 💡 **Key Insight**
321+
The underscore pattern is **not inconsistent** - it's a logical way to represent component hierarchy:
322+
- SitePage uses underscores **instead of** subdirectories (flat but organized)
323+
- TimeWarpPage uses subdirectories **plus** underscores (deeply nested but still organized)
324+
325+
**This is actually a sophisticated component organization system that just needs proper documentation!**

0 commit comments

Comments
 (0)