From 5f9def40d99636aaf59da594de4a74395ae6583c Mon Sep 17 00:00:00 2001
From: MayaTheShy <MayaTheShy@gmail.com>
Date: Sun, 9 Nov 2025 03:13:09 -0500
Subject: [PATCH] docs: add DIRECTORY_STRUCTURE.md to document project
 organization and file layout

---
 docs/DIRECTORY_STRUCTURE.md | 195 ++++++++++++++++++++++++++++++++++++
 docs/README.md              |   1 +
 2 files changed, 196 insertions(+)
 create mode 100644 docs/DIRECTORY_STRUCTURE.md

diff --git a/docs/DIRECTORY_STRUCTURE.md b/docs/DIRECTORY_STRUCTURE.md
new file mode 100644
index 0000000..3c1508e
--- /dev/null
+++ b/docs/DIRECTORY_STRUCTURE.md
@@ -0,0 +1,195 @@
+# Directory Structure
+
+## Root Directory Layout
+
+```
+Starworld/
+├── README.md                # Main project documentation
+├── LICENSE                  # Project license
+├── CMakeLists.txt          # CMake build configuration
+├── build_and_test.sh       # Convenience wrapper (points to scripts/)
+│
+├── src/                    # C++ source code
+├── bridge/                 # Rust StardustXR bridge
+├── tests/                  # C++ test suite
+├── tools/                  # Python utilities (Blender export, etc.)
+│
+├── docs/                   # All documentation files
+├── scripts/                # Build and utility scripts
+├── examples/               # Example files and test data
+│
+├── build/                  # CMake build output (gitignored)
+└── third_party/            # Vendored dependencies (optional)
+```
+
+## Directory Purposes
+
+### `/src`
+C++ source code for the Overte client:
+- `main.cpp` - Entry point
+- `OverteClient.cpp` - Overte protocol implementation
+- `StardustBridge.cpp` - C++/Rust bridge interface
+- `SceneSync.cpp` - Entity synchronization
+- `NLPacketCodec.cpp` - Packet encoding/decoding
+- `QDataStream.cpp` - Qt serialization
+
+### `/bridge`
+Rust implementation of StardustXR client:
+- `src/lib.rs` - Bridge implementation with C ABI
+- `Cargo.toml` - Rust dependencies
+- Compiled to `libstardust_bridge.so`
+
+### `/tests`
+C++ test harness:
+- `TestHarness.cpp` - Unit tests
+- `CMakeLists.txt` - Test build configuration
+
+### `/tools`
+Python utilities:
+- `blender_export_simple.py` - Generate primitive models
+- Other development tools
+
+### `/docs` (NEW)
+All project documentation:
+- `README.md` - Documentation index
+- `DEVELOPER_GUIDE.md` - Quick reference
+- `CHANGELOG.md` - Version history
+- `OVERTE_*.md` - Overte protocol docs
+- `*_IMPLEMENTATION.md` - Implementation details
+- `CI_SETUP_SUMMARY.md` - CI/CD documentation
+
+### `/scripts` (NEW)
+Build and utility scripts:
+- `build_and_test.sh` - Full clean build and test
+- `ci-test.sh` - CI test script
+- `run_with_auth.sh` - Run with authentication (future)
+
+### `/examples` (NEW)
+Example files and test data:
+- `test_entities.json` - Sample entity configuration
+- `primitives/` - Pre-built primitive models (cube, sphere)
+
+### `/third_party`
+Vendored dependencies (optional):
+- StardustXR crates (core, asteroids)
+- Other dependencies for deterministic builds
+
+### `/build`
+CMake build output (not in git):
+- `starworld` - Main executable
+- `starworld-tests` - Test executable
+- `*.o` - Object files
+
+## File Organization Principles
+
+### Root Directory (Keep Clean!)
+Only essential files in the root:
+- Main documentation (README.md)
+- Build configuration (CMakeLists.txt)
+- License
+- Optional: Top-level convenience scripts
+
+### Documentation
+All `.md` files (except README) go in `/docs`:
+- Organized by topic
+- Linked from main README
+- Cross-referenced with relative links
+
+### Scripts
+All `.sh` scripts go in `/scripts`:
+- Build scripts
+- Test scripts
+- Utility scripts
+- Development helpers
+
+### Examples
+Test data and examples go in `/examples`:
+- Sample configurations
+- Test models
+- Example entities
+
+## Migrating Old Paths
+
+If you have scripts or documentation referencing old paths:
+
+### Documentation Files
+```
+OLD: ./DEVELOPER_GUIDE.md
+NEW: ./docs/DEVELOPER_GUIDE.md
+
+OLD: ./OVERTE_AUTH.md  
+NEW: ./docs/OVERTE_AUTH.md
+```
+
+### Scripts
+```
+OLD: ./build_and_test.sh (still works as wrapper)
+NEW: ./scripts/build_and_test.sh (actual script)
+
+OLD: ./ci-test.sh
+NEW: ./scripts/ci-test.sh
+```
+
+### Examples
+```
+OLD: ./test_entities.json
+NEW: ./examples/test_entities.json
+
+OLD: ./primitives/
+NEW: ./examples/primitives/
+```
+
+## Benefits of New Structure
+
+1. **Cleaner Root**: Easy to see what the project is about
+2. **Logical Grouping**: Similar files together
+3. **Scalability**: Easy to add new docs/scripts/examples
+4. **Navigation**: Clear where to find things
+5. **Professional**: Matches common open-source project layouts
+
+## Comparison
+
+### Before
+```
+Starworld/
+├── README.md
+├── DEVELOPER_GUIDE.md
+├── CHANGELOG.md
+├── OVERTE_AUTH.md
+├── OVERTE_ASSIGNMENT_CLIENT_TASK.md
+├── ENTITY_RENDERING_ENHANCEMENTS.md
+├── MODELCACHE_IMPLEMENTATION.md
+├── CI_SETUP_SUMMARY.md
+├── CODE_CLEANUP_PLAN.md
+├── build_and_test.sh
+├── ci-test.sh
+├── run_with_auth.sh
+├── test_entities.json
+├── primitives/
+├── CMakeLists.txt
+├── LICENSE
+├── src/
+├── bridge/
+├── tests/
+├── tools/
+└── third_party/
+```
+
+### After
+```
+Starworld/
+├── README.md
+├── CMakeLists.txt
+├── LICENSE
+├── build_and_test.sh    (wrapper)
+├── src/
+├── bridge/
+├── tests/
+├── tools/
+├── docs/                (8 .md files)
+├── scripts/             (3 .sh files)
+├── examples/            (test data, primitives)
+└── third_party/
+```
+
+Much better! 🎉
diff --git a/docs/README.md b/docs/README.md
index 8d8be2f..cd923ea 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@ This directory contains all project documentation organized by topic.
 ### Getting Started
 - **[../README.md](../README.md)** - Main project README with quick start guide
 - **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Developer quick reference with commands and tips
+- **[DIRECTORY_STRUCTURE.md](DIRECTORY_STRUCTURE.md)** - Project organization and file layout
 
 ### Project Information
 - **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes