Starworld/docs/DIRECTORY_STRUCTURE.md

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! 🎉