|
| 1 | +# FlatCityBuf Project Structure |
| 2 | + |
| 3 | +``` |
| 4 | +flatcitybuf/ |
| 5 | +│ |
| 6 | +├── 📄 README.md # Project overview and getting started guide |
| 7 | +├── 📄 CLAUDE.md # AI/LLM coding guidelines for this repository |
| 8 | +├── 📄 CONTRIBUTING.md # Contribution guidelines |
| 9 | +├── 📄 LICENSE # MIT License |
| 10 | +│ |
| 11 | +├── 📁 .llm/ # AI/LLM context and documentation |
| 12 | +│ └── docs/ |
| 13 | +│ ├── productContext.md # Project purpose, problem, and goals |
| 14 | +│ ├── specification.md # FlatCityBuf encoding specification |
| 15 | +│ └── projectStructure.md # This file - folder structure overview |
| 16 | +│ |
| 17 | +├── 📁 docs/ # Public documentation and assets |
| 18 | +│ ├── logo.png # Project logo |
| 19 | +│ └── ... |
| 20 | +│ |
| 21 | +├── 📁 examples/ # Usage examples and tutorials |
| 22 | +│ └── data/ # Example data files |
| 23 | +│ └── delft.fcb # Sample FlatCityBuf file |
| 24 | +│ |
| 25 | +├── 📁 scripts/ # Build and utility scripts |
| 26 | +│ |
| 27 | +├── 📁 src/ # Source code root |
| 28 | +│ │ |
| 29 | +│ ├── 📁 fbs/ # FlatBuffers schema definitions |
| 30 | +│ │ └── cityjson.fbs # CityJSON FlatBuffers schema |
| 31 | +│ │ |
| 32 | +│ ├── 📁 rust/ # Rust workspace (core implementation) |
| 33 | +│ │ ├── 📄 Cargo.toml # Workspace configuration |
| 34 | +│ │ ├── 📄 Cargo.lock # Dependency lock file |
| 35 | +│ │ ├── 📄 CLAUDE.md # Rust-specific coding guidelines |
| 36 | +│ │ ├── 📄 Dockerfile # Docker image for Rust builds |
| 37 | +│ │ ├── 📄 makefile # Build automation |
| 38 | +│ │ │ |
| 39 | +│ │ ├── 📁 cli/ # fcb_cli - Command-line interface |
| 40 | +│ │ │ ├── src/ |
| 41 | +│ │ │ │ └── main.rs # CLI entry point |
| 42 | +│ │ │ └── Cargo.toml |
| 43 | +│ │ │ |
| 44 | +│ │ ├── 📁 fcb_core/ # Core library (crate) |
| 45 | +│ │ │ ├── src/ |
| 46 | +│ │ │ │ ├── lib.rs # Library entry point |
| 47 | +│ │ │ │ ├── http/ # HTTP range request client |
| 48 | +│ │ │ │ ├── index/ # Spatial (Packed R-tree) & Attribute (B+Tree) indexing |
| 49 | +│ │ │ │ ├── reader/ # FlatBuffers reading & deserialization |
| 50 | +│ │ │ │ └── writer/ # FlatBuffers writing & serialization |
| 51 | +│ │ │ └── Cargo.toml |
| 52 | +│ │ │ |
| 53 | +│ │ ├── 📁 fcb_py/ # Python bindings (PyO3) |
| 54 | +│ │ │ ├── src/ |
| 55 | +│ │ │ │ └── lib.rs # FFI bridge to Python |
| 56 | +│ │ │ └── Cargo.toml |
| 57 | +│ │ │ |
| 58 | +│ │ ├── 📁 fcb_cpp/ # C++ bindings (cxx bridge) |
| 59 | +│ │ │ ├── src/ |
| 60 | +│ │ │ │ └── lib.rs # FFI bridge to C++ |
| 61 | +│ │ │ └── Cargo.toml |
| 62 | +│ │ │ |
| 63 | +│ │ ├── 📁 wasm/ # WebAssembly bindings (wasm-bindgen) |
| 64 | +│ │ │ ├── src/ |
| 65 | +│ │ │ │ └── lib.rs # FFI bridge to JS/TS |
| 66 | +│ │ │ └── Cargo.toml |
| 67 | +│ │ │ |
| 68 | +│ │ ├── 📁 fcb_api/ # REST API server (axum) |
| 69 | +│ │ │ ├── src/ |
| 70 | +│ │ │ │ └── main.rs # API server entry point |
| 71 | +│ │ │ └── Cargo.toml |
| 72 | +│ │ │ |
| 73 | +│ │ └── 📁 data/ # Test data and fixtures |
| 74 | +│ │ |
| 75 | +│ ├── 📁 cpp/ # C++ library bindings |
| 76 | +│ │ ├── 📁 include/ # Public C++ headers |
| 77 | +│ │ │ └── flatcitybuf/ |
| 78 | +│ │ │ └── flatcitybuf.hpp |
| 79 | +│ │ ├── 📁 examples/ # C++ usage examples |
| 80 | +│ │ │ └── example.cpp |
| 81 | +│ │ ├── 📁 build/ # C++ build artifacts (generated) |
| 82 | +│ │ ├── 📄 CMakeLists.txt # CMake build configuration |
| 83 | +│ │ └── 📄 Doxyfile # Doxygen documentation config |
| 84 | +│ │ |
| 85 | +│ └── 📁 ts/ # TypeScript/JavaScript package |
| 86 | +│ ├── 📄 package.json # npm package config |
| 87 | +│ ├── 📄 tsconfig.json # TypeScript config |
| 88 | +│ ├── 📄 fcb_wasm.js # Generated WASM bindings |
| 89 | +│ ├── 📄 fcb_wasm_bg.wasm # WebAssembly binary |
| 90 | +│ ├── 📄 fcb_wasm.d.ts # TypeScript definitions |
| 91 | +│ └── 📄 index.html # Demo/preview page |
| 92 | +│ |
| 93 | +├── 📁 data/ # Development data files |
| 94 | +│ └── out/ # Output files from conversions |
| 95 | +│ |
| 96 | +├── 📁 .agent/ # Agent configuration (for AI tools) |
| 97 | +│ └── rules/ |
| 98 | +│ |
| 99 | +├── 📁 .cursor/ # Cursor IDE configuration |
| 100 | +│ └── rules/ |
| 101 | +│ |
| 102 | +├── 📁 .serena/ # Serena AI cache |
| 103 | +│ ├── cache/ |
| 104 | +│ └── memories/ |
| 105 | +│ |
| 106 | +└── 📁 .vscode/ # VS Code configuration |
| 107 | + └── settings.json |
| 108 | +``` |
| 109 | + |
| 110 | +## Component Overview |
| 111 | + |
| 112 | +### Rust Workspace (`src/rust/`) |
| 113 | + |
| 114 | +The Rust workspace is organized as a multi-crate project with the following members: |
| 115 | + |
| 116 | +| Crate | Purpose | Language Bindings | |
| 117 | +|-------|---------|-------------------| |
| 118 | +| **fcb_core** | Core library with read/write/indexing capabilities | Pure Rust | |
| 119 | +| **cli** | Command-line interface (`fcb` command) | - | |
| 120 | +| **fcb_py** | Python bindings via PyO3 | Python | |
| 121 | +| **fcb_cpp** | C++ bindings via cxx bridge | C++ | |
| 122 | +| **wasm** | WebAssembly bindings via wasm-bindgen | JavaScript/TypeScript | |
| 123 | +| **fcb_api** | REST API server using axum | HTTP API | |
| 124 | + |
| 125 | +### Language Bindings |
| 126 | + |
| 127 | +FlatCityBuf provides native bindings for multiple languages: |
| 128 | + |
| 129 | +1. **Python** (`src/rust/fcb_py/`) → Published to PyPI as `flatcitybuf` |
| 130 | +2. **C++** (`src/cpp/`) → Standalone C++ library with CMake build |
| 131 | +3. **JavaScript/TypeScript** (`src/ts/`) → Published to npm as `@cityjson/flatcitybuf` |
| 132 | + |
| 133 | +### Build Artifacts (Not Tracked) |
| 134 | + |
| 135 | +- `src/rust/target/` - Rust build artifacts (in `.gitignore`) |
| 136 | +- `src/cpp/build/` - C++ build artifacts (in `.gitignore`) |
| 137 | + |
| 138 | +## Key Patterns |
| 139 | + |
| 140 | +### Workspace Dependency Management |
| 141 | + |
| 142 | +All dependencies are managed at the workspace level in `src/rust/Cargo.toml`. Individual crates use workspace dependencies: |
| 143 | + |
| 144 | +```toml |
| 145 | +[dependencies] |
| 146 | +fcb_core = { workspace = true } |
| 147 | +``` |
| 148 | + |
| 149 | +### Code Organization |
| 150 | + |
| 151 | +Each crate follows standard Rust conventions: |
| 152 | +- `src/lib.rs` - Library entry point |
| 153 | +- `src/main.rs` - Binary entry point |
| 154 | +- Feature flags in `Cargo.toml` for conditional compilation |
| 155 | + |
| 156 | +### Cross-Language Bridge |
| 157 | + |
| 158 | +Language bindings use appropriate FFI technologies: |
| 159 | +- **Python**: PyO3 with async runtime support |
| 160 | +- **C++**: cxx bridge for automatic Rust/C++ interoperability |
| 161 | +- **WASM**: wasm-bindgen for browser compatibility |
0 commit comments