Skip to content

Commit ba406d1

Browse files
mbertelsenmbertelsen
committed
Standardizes docs structure and placement
Moves all technical docs into docs/technical and updates index for discoverability Renames/normalizes Azure docs (including Front Door) for consistent naming Adds strict documentation placement rules to .ai-context.md to prevent .md files in code dirs Migrates component-specific README to technical docs and adds refactoring summary Removes orphaned WebhookModal.css Improves consistency, reduces repo clutter, and clarifies contributor/AI guidelines
1 parent 27dc035 commit ba406d1

12 files changed

+302
-93
lines changed

‎.ai-context.md‎

Lines changed: 48 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,40 @@
11
# AI Assistant Context File
22

3-
> **Purpose**: This file | Working On | Read This |
4-
|------------|-----------|
5-
| Event handling | [ACTIVITY_SESSION_STATE.md](./docs/technical/ACTIVITY_SESSION_STATE.md) |
6-
| Measurement display | [MEASUREMENT_TILES_MULTI_EVENT.md](./docs/technical/MEASUREMENT_TILES_MULTI_EVENT.md) |
7-
| Hole/shot tracking | [SHOT_NUMBER_CARRY_FORWARD_FIX.md](./docs/technical/SHOT_NUMBER_CARRY_FORWARD_FIX.md) |
8-
| Course info & images | [HOLE_IMAGE_DISPLAY.md](./docs/technical/HOLE_IMAGE_DISPLAY.md) |
9-
| Shot trajectory overlay | [SHOT_TRAJECTORY_VISUALIZATION.md](./docs/technical/SHOT_TRAJECTORY_VISUALIZATION.md) |
10-
| Unit conversion | [UNIT_CONVERSION_SYSTEM.md](./docs/technical/UNIT_CONVERSION_SYSTEM.md) |
11-
| Filtering events | [DEVICE_ID_FILTERING.md](./docs/technical/DEVICE_ID_FILTERING.md) |
12-
| Local development | [WEBHOOK_LOCAL_FIX.md](./docs/technical/WEBHOOK_LOCAL_FIX.md) |
13-
| Azure Storage | [LOCAL_AZURE_STORAGE_SETUP.md](./docs/technical/LOCAL_AZURE_STORAGE_SETUP.md) |ssistants understand the project structure and where to find documentation.
3+
> **Purpose**: This file helps AI assistants understand the project structure and where to find documentation.
4+
5+
## ⚠️ CRITICAL RULE: Documentation File Placement
6+
7+
### ❌ NEVER create `.md` files in these locations:
8+
- ❌ **Root directory** (except readme.md, NEXT_STEPS.md, DOCUMENTATION_README.md)
9+
- ❌ **src/** or any subdirectories
10+
- ❌ **src/components/** or component folders
11+
- ❌ **server/** (except server/README.md which already exists)
12+
- ❌ **Any code directory**
13+
14+
### ✅ ALWAYS create technical documentation here:
15+
- ✅ **`docs/technical/`** - All implementation docs, bug fixes, feature docs
16+
- ✅ **`docs/`** - Only user-facing guides (authoring, user guides, etc.)
17+
18+
### 📝 When You Create Documentation:
19+
1. **Check**: Is this technical/implementation documentation?
20+
- ✅ YES → Create in `docs/technical/FEATURE_NAME.md`
21+
- ❌ NO → Is it a user guide? Create in `docs/USER_GUIDE_NAME.md`
22+
23+
2. **Update the index**: Add your new file to `docs/technical/README.md`
24+
25+
3. **Use proper naming**:
26+
- Technical docs: `FEATURE_NAME.md` or `FIX_DESCRIPTION.md` (ALL_CAPS)
27+
- User docs: `kebab-case.md` (lowercase-with-hyphens)
28+
29+
### 🚨 If User Says "You Created .md Files in Wrong Place":
30+
This means you violated this rule. Immediately:
31+
1. Apologize
32+
2. Move ALL misplaced `.md` files to `docs/technical/`
33+
3. Update `docs/technical/README.md` to include them
34+
4. Delete the misplaced files
35+
5. Verify no orphaned `.md` files remain in code directories
36+
37+
---
1438

1539
## 📂 Project Structure
1640

@@ -55,15 +79,21 @@
5579

5680
### When Creating New Features
5781
1. Implement the feature
58-
2. Create documentation in `docs/technical/FEATURE_NAME.md`
82+
2. **ALWAYS** create documentation in `docs/technical/FEATURE_NAME.md` (**NOT in root or src/**)
5983
3. Update [`docs/technical/README.md`](./docs/technical/README.md) to include your new doc
6084
4. Use the template structure provided in the README
6185

6286
### When Fixing Bugs
6387
1. Check if a fix already exists in `docs/technical/`
6488
2. Implement the fix
65-
3. Document it in `docs/technical/FIX_DESCRIPTION.md`
66-
4. Update the index
89+
3. **ALWAYS** document it in `docs/technical/FIX_DESCRIPTION.md` (**NOT in root or src/**)
90+
4. Update the index in `docs/technical/README.md`
91+
92+
### When Adding Deployment/Infrastructure Changes
93+
1. Implement the changes
94+
2. **ALWAYS** document in `docs/technical/DEPLOYMENT_*.md` or `docs/technical/AZURE_*.md`
95+
3. Never create `DEPLOYMENT_FIX.md` or `AZURE_*.md` in root directory
96+
4. Update `docs/technical/README.md` index
6797

6898
## 📚 Key Documentation Files
6999

@@ -117,8 +147,10 @@ const payload = event?.data?.EventModel || event?.EventModel || event;
117147
1. **Don't assume event order** - Newest is at index 0, not at the end
118148
2. **Don't store transient data in session state** - Only store truly shared data (like course info)
119149
3. **Don't forget SSE updates** - Changes must work for both initial load AND real-time updates
120-
4. **Don't skip documentation** - Always document significant changes
121-
5. **Don't create root-level .md files** - Put technical docs in `docs/technical/`
150+
4. **Don't skip documentation** - Always document significant changes in `docs/technical/`
151+
5. **❌ NEVER create .md files in root or src/** - Use `docs/technical/` instead
152+
6. **❌ NEVER create component READMEs** - Move to `docs/technical/COMPONENT_NAME.md`
153+
7. **Don't forget to update** `docs/technical/README.md` when adding new docs
122154

123155
## 💾 Key State Management
124156

AZURE_DEPLOYMENT_SETUP.md renamed to docs/technical/AZURE_DEPLOYMENT_SETUP.md

File renamed without changes.

AZURE-FRONTDOOR.md renamed to docs/technical/AZURE_FRONTDOOR.md

File renamed without changes.

AZURE_STORAGE_QUICK_SETUP.md renamed to docs/technical/AZURE_STORAGE_QUICK_SETUP.md

File renamed without changes.

AZURE_TABLE_STORAGE_SETUP.md renamed to docs/technical/AZURE_TABLE_STORAGE_SETUP.md

File renamed without changes.

‎docs/technical/COMPONENT_REFACTORING_2025_10.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Component Organization Refactoring - October 2025
2+
3+
## Overview
4+
5+
Complete dependency-based refactoring of React component structure to improve code organization, maintainability, and developer experience.
6+
7+
## Problem
8+
9+
Components were scattered in a flat `src/components/` directory without clear organization. Many components that were only used by one parent component were mixed with truly shared components, making it difficult to understand dependencies and navigate the codebase.
10+
11+
## Solution
12+
13+
Implemented dependency-based organization where:
14+
- **Single-parent components** → Moved into parent's feature folder
15+
- **Multi-parent components** → Kept in shared `components/` directory
16+
- **Unused/orphaned components** → Deleted
17+
- **Related components** → Grouped into feature folders
18+
19+
## Implementation
20+
21+
### Feature Folders Created (8 total)
22+
23+
1. **Sidebar/** (10 files)
24+
- Main orchestrator: `index.tsx`
25+
- Sub-components: `SidebarFileOperations`, `SidebarBayOperations`, `SidebarEditOperations`, `SidebarValidationPanel`
26+
- Exclusive dependencies: `BaySelector`, `LocationSelector`, `TreeView`
27+
- Supporting files: `types/sidebarTypes.ts`, `hooks/useScriptExecution.ts`
28+
29+
2. **NodeEditor/** (7 files)
30+
- Main editor: `index.tsx`
31+
- Exclusive dependencies: `UIEditor`, `SetupEditor`, `SubTabBar`, `MessageEditor`
32+
- All components only used within NodeEditor
33+
34+
3. **WebhookInspector/** (9 files)
35+
- Main component: `index.tsx`
36+
- Exclusive dependencies: `MeasurementTilesView`, `CourseInfoBanner`, `ShotTrajectoryOverlay`
37+
- Utility modules for webhook event processing
38+
39+
4. **WebhookView/** (4 files)
40+
- Main view: `index.tsx`
41+
- Event panel: `WebhookEventsPanel.tsx`
42+
- Associated CSS files
43+
44+
5. **HoleSelector/** (4 files)
45+
- Main selector: `index.tsx`
46+
- Layout/Card components: `HoleLayout`, `HoleCard`
47+
- CSS file
48+
49+
6. **FacilitySelector/** (3 files)
50+
- Portal selector: `index.tsx`
51+
- Alternative dropdown: `FacilityDropdown`
52+
- CSS file
53+
54+
7. **Dialogs/** (3 files)
55+
- Dialog manager: `index.tsx`
56+
- Dialog types: `ActivityDialog`, `StepDialog`
57+
58+
8. **TopBar/** (2 files)
59+
- Main component: `index.tsx`
60+
- Exclusive dependency: `BuildVersion`
61+
62+
### Components Kept Shared
63+
64+
- **CollapsibleSection.tsx** - Used by Sidebar (3 files) + ScriptEditor (truly shared utility)
65+
- **ScriptEditor.tsx** - App-level component used by multiple routes
66+
- **DocViewer.tsx** - App-level component used by multiple routes
67+
- **TabBar.tsx** - App-level component
68+
- **buttons/** - Shared button components used across features
69+
70+
### Files Deleted (9 total)
71+
72+
**Orphaned files (no imports found):**
73+
1. `FacilitiesDemo.tsx` - Unused demo file
74+
2. `NodeDetailsPanel.tsx` - Orphaned, no references
75+
3. `EditPanel.tsx` - Only used by deleted NodeDetailsPanel
76+
4. `ConditionEditor.tsx` - Only used by deleted NodeDetailsPanel
77+
5. `AuthStatus.tsx` - No imports found
78+
6. `LoginPage.tsx` - No imports found
79+
7. `UserProfile.tsx` - No imports found
80+
8. `Switch.tsx` - No imports found
81+
9. `WebhookModal.css` - No imports found
82+
83+
### Import Path Updates
84+
85+
All imports updated to reflect new structure:
86+
- Feature folder components import siblings with `'./'`
87+
- Feature folder components import from parent with `'../'`
88+
- Feature folder components import shared components with `'../ComponentName'`
89+
- App-level files import feature folders with `'./components/FeatureName'`
90+
91+
**Example:**
92+
```typescript
93+
// Before (flat structure)
94+
import { TreeView } from './TreeView';
95+
96+
// After (feature folder)
97+
// In Sidebar/SidebarEditOperations.tsx
98+
import { TreeView } from './TreeView';
99+
```
100+
101+
## File Movements
102+
103+
### Sidebar Enhancements
104+
- `TreeView.tsx` → `Sidebar/TreeView.tsx`
105+
- `BaySelector.tsx` → `Sidebar/BaySelector.tsx`
106+
- `LocationSelector.tsx` → `Sidebar/LocationSelector.tsx`
107+
108+
### NodeEditor Group
109+
- `NodeEditor.tsx` → `NodeEditor/index.tsx`
110+
- `UIEditor.tsx` + `.css` → `NodeEditor/`
111+
- `SetupEditor.tsx` → `NodeEditor/`
112+
- `SubTabBar.tsx` + `.css` → `NodeEditor/`
113+
- `MessageEditor.tsx` → `NodeEditor/`
114+
115+
### WebhookInspector Enhancements
116+
- `MeasurementTilesView.tsx` + `.css` + `.README.md` → `WebhookInspector/`
117+
- `CourseInfoBanner.tsx` + `.css` → `WebhookInspector/`
118+
- `ShotTrajectoryOverlay.tsx` + `.css` → `WebhookInspector/`
119+
120+
### TopBar Feature Folder
121+
- `TopBar.tsx` → `TopBar/index.tsx`
122+
- `BuildVersion.tsx` → `TopBar/BuildVersion.tsx`
123+
124+
## Testing
125+
126+
✅ **Build Verification:**
127+
- Vite dev server: Ready in 512ms
128+
- Express backend: Started successfully on port 4000
129+
- Azure Table Storage: Initialized
130+
- No TypeScript compilation errors
131+
132+
✅ **Import Path Verification:**
133+
- All relative imports updated correctly
134+
- No broken import paths
135+
- Module resolution working as expected
136+
137+
## Benefits
138+
139+
### Developer Experience
140+
- ✅ **Clear dependencies**: Easy to see what components are used where
141+
- ✅ **Better navigation**: Related files grouped together
142+
- ✅ **Reduced cognitive load**: Fewer files in root components directory
143+
- ✅ **Easier refactoring**: Moving a feature means moving one folder
144+
145+
### Code Organization
146+
- ✅ **Feature-based structure**: Components grouped by feature domain
147+
- ✅ **Dependency clarity**: Single-parent vs. multi-parent immediately obvious
148+
- ✅ **Reduced clutter**: From 28+ files in root to 8 organized folders
149+
- ✅ **Better encapsulation**: Feature-specific code stays within feature folder
150+
151+
### Maintainability
152+
- ✅ **Less confusion**: No more guessing about component relationships
153+
- ✅ **Easier testing**: Feature folders can be tested in isolation
154+
- ✅ **Better onboarding**: New developers can understand structure quickly
155+
- ✅ **Cleaner git history**: Changes grouped by feature
156+
157+
## Final Structure
158+
159+
```
160+
src/components/
161+
├── buttons/ # Shared button components
162+
├── CollapsibleSection.tsx # Shared utility (Sidebar + ScriptEditor)
163+
├── Dialogs/ # 3 dialog components
164+
│ ├── index.tsx
165+
│ ├── ActivityDialog.tsx
166+
│ └── StepDialog.tsx
167+
├── DocViewer.tsx # App-level component
168+
├── FacilitySelector/ # 3 facility selector components
169+
├── HoleSelector/ # 4 hole selector components
170+
├── NodeEditor/ # 7 node editor components
171+
│ ├── index.tsx
172+
│ ├── UIEditor.tsx + .css
173+
│ ├── SetupEditor.tsx
174+
│ ├── SubTabBar.tsx + .css
175+
│ └── MessageEditor.tsx
176+
├── ScriptEditor.tsx # App-level component
177+
├── Sidebar/ # 10 sidebar components
178+
│ ├── index.tsx
179+
│ ├── BaySelector.tsx
180+
│ ├── LocationSelector.tsx
181+
│ ├── TreeView.tsx
182+
│ ├── SidebarBayOperations.tsx
183+
│ ├── SidebarEditOperations.tsx
184+
│ ├── SidebarFileOperations.tsx
185+
│ ├── SidebarValidationPanel.tsx
186+
│ ├── types/sidebarTypes.ts
187+
│ └── hooks/useScriptExecution.ts
188+
├── TabBar.tsx + .css # App-level component
189+
├── TopBar/ # 2 TopBar components
190+
│ ├── index.tsx
191+
│ └── BuildVersion.tsx
192+
├── WebhookInspector/ # 9 webhook inspector components
193+
│ ├── index.tsx
194+
│ ├── CourseInfoBanner.tsx + .css
195+
│ ├── MeasurementTilesView.tsx + .css
196+
│ ├── ShotTrajectoryOverlay.tsx + .css
197+
│ └── (utility modules)
198+
└── WebhookView/ # 4 webhook view components
199+
├── index.tsx
200+
└── WebhookEventsPanel.tsx + .css
201+
```
202+
203+
## Lessons Learned
204+
205+
1. **Dependency analysis is crucial** - Understanding single-parent vs. multi-parent relationships before moving files saves time
206+
207+
2. **Move related files together** - CSS, hooks, and types should move with their components
208+
209+
3. **Update imports carefully** - Use find/replace with file path validation
210+
211+
4. **Test incrementally** - Verify each feature folder works before moving to the next
212+
213+
5. **Delete unused code** - Don't just move orphaned files, delete them
214+
215+
## Related Documentation
216+
217+
- [Documentation Organization](./DOCUMENTATION_ORGANIZATION_SUMMARY.md) - How documentation is structured
218+
- [.ai-context.md](../../.ai-context.md) - AI assistant guidelines including documentation placement rules
219+
220+
## Future Considerations
221+
222+
### Potential Further Refactoring
223+
- Consider creating `WebhookInspector/utils/` subfolder for utility modules
224+
- Evaluate if `buttons/` should be broken down by feature usage
225+
- Consider TypeScript barrel exports for cleaner imports
226+
227+
### Guidelines for New Components
228+
1. **Ask first**: Is this used by one feature or multiple?
229+
2. **Single parent**: Create in parent's feature folder
230+
3. **Multiple parents**: Keep in shared `components/`
231+
4. **Always group**: Related CSS, hooks, types should stay together
232+
233+
---
234+
235+
**Refactoring Date**: October 8, 2025
236+
**Files Moved**: 35+
237+
**Files Deleted**: 9
238+
**Feature Folders Created**: 8
239+
**Build Status**: ✅ Successful
240+
**Runtime Status**: ✅ Verified working

DEBUGGING_ENHANCEMENT.md renamed to docs/technical/DEBUGGING_ENHANCEMENT.md

File renamed without changes.

DEPLOYMENT_FIX.md renamed to docs/technical/DEPLOYMENT_FIX.md

File renamed without changes.

DOCKER_DEPLOYMENT.md renamed to docs/technical/DOCKER_DEPLOYMENT.md

File renamed without changes.

src/components/WebhookInspector/MeasurementTilesView.README.md renamed to docs/technical/MEASUREMENT_TILES_VIEW.md

File renamed without changes.

0 commit comments

Comments
 (0)