|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +libgraph is a modern, header-only C++11 library for graph construction and pathfinding algorithms. It provides high-performance graph operations with thread-safe concurrent searches and support for generic cost types. The library implements a Graph class using an adjacency list representation with O(m+n) space complexity and provides a unified search framework with A*, Dijkstra, BFS, and DFS algorithms. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +### Basic Build |
| 12 | +```bash |
| 13 | +mkdir build && cd build |
| 14 | +cmake .. |
| 15 | +cmake --build . |
| 16 | +``` |
| 17 | + |
| 18 | +### Build with Tests |
| 19 | +```bash |
| 20 | +mkdir build && cd build |
| 21 | +cmake -DBUILD_TESTING=ON .. |
| 22 | +cmake --build . |
| 23 | +``` |
| 24 | + |
| 25 | +### Build with Coverage |
| 26 | +```bash |
| 27 | +mkdir build && cd build |
| 28 | +cmake -DBUILD_TESTING=ON -DCOVERAGE_CHECK=ON .. |
| 29 | +cmake --build . |
| 30 | +``` |
| 31 | + |
| 32 | +### Run Tests |
| 33 | +```bash |
| 34 | +cd build |
| 35 | +make test |
| 36 | +# or run directly |
| 37 | +./bin/utests |
| 38 | +``` |
| 39 | + |
| 40 | +### Generate Documentation |
| 41 | +```bash |
| 42 | +cd docs |
| 43 | +doxygen doxygen/Doxyfile |
| 44 | +``` |
| 45 | + |
| 46 | +### Create Installation Package |
| 47 | +```bash |
| 48 | +cd build |
| 49 | +cpack # Creates .deb package |
| 50 | +``` |
| 51 | + |
| 52 | +## Code Architecture |
| 53 | + |
| 54 | +### Core Components |
| 55 | + |
| 56 | +The library is organized around three main template classes in the `xmotion` namespace: |
| 57 | + |
| 58 | +1. **Graph<State, Transition, StateIndexer>** (`src/include/graph/graph.hpp`) |
| 59 | + - Main graph class using adjacency list representation |
| 60 | + - Uses `std::unordered_map<int64_t, Vertex*>` for vertex storage |
| 61 | + - Each vertex contains `std::list<Edge>` for edges |
| 62 | + - Supports directed and undirected graphs |
| 63 | + - Provides vertex/edge iterators for traversal |
| 64 | + |
| 65 | +2. **Tree<State, Transition, StateIndexer>** (`src/include/graph/tree.hpp`) |
| 66 | + - Specialized graph structure for tree representations |
| 67 | + - Enforces tree properties (single parent, no cycles) |
| 68 | + |
| 69 | +3. **Search Algorithms** (`src/include/graph/search/`) |
| 70 | + - `AStar`: A* pathfinding with custom heuristics |
| 71 | + - `Dijkstra`: Shortest path algorithm for weighted graphs |
| 72 | + - `BFS`: Breadth-first search for unweighted shortest paths |
| 73 | + - `DFS`: Depth-first search for graph traversal |
| 74 | + - All algorithms use unified framework with `SearchContext` for thread-safe concurrent searches |
| 75 | + - Dynamic priority queue implementation for efficient priority updates |
| 76 | + |
| 77 | +### State Indexing System |
| 78 | + |
| 79 | +The library uses a StateIndexer functor to generate unique indices for graph vertices: |
| 80 | +- **DefaultIndexer** (`src/include/graph/impl/default_indexer.hpp`): Automatically works with states that have `GetId()`, `id_`, or `id` |
| 81 | +- Custom indexers can be defined by implementing `operator()(State)` returning `int64_t` |
| 82 | + |
| 83 | +### Priority Queue Implementation |
| 84 | + |
| 85 | +The search algorithms rely on specialized priority queues: |
| 86 | +- **PriorityQueue** (`src/include/graph/impl/priority_queue.hpp`): Basic priority queue |
| 87 | +- **DynamicPriorityQueue** (`src/include/graph/impl/dynamic_priority_queue.hpp`): Supports priority updates, crucial for efficient graph searches |
| 88 | + |
| 89 | +## Testing Structure |
| 90 | + |
| 91 | +- **Unit Tests** (`tests/unit_test/`): Core functionality tests using Google Test |
| 92 | + - Graph construction, modification, iteration |
| 93 | + - Search algorithm correctness |
| 94 | + - Priority queue operations |
| 95 | + - Tree operations |
| 96 | +- **Development Tests** (`tests/devel_test/`): Performance and specialized tests |
| 97 | + |
| 98 | +## Important Implementation Details |
| 99 | + |
| 100 | +- The library is header-only; all implementation is in `.hpp` files |
| 101 | +- Graph vertices are stored as pointers in an unordered_map for O(1) average access |
| 102 | +- Edge lists use std::list for O(1) insertion |
| 103 | +- The library exports as `xmotion::graph` when installed via CMake |
| 104 | +- Namespace `xmotion` is used throughout to avoid naming conflicts |
| 105 | +- Thread-safe concurrent searches using external `SearchContext` |
| 106 | +- Support for custom cost types with `CostTraits` specialization |
| 107 | +- RAII memory management with `std::unique_ptr` for exception safety |
| 108 | +- Modern C++ design patterns including CRTP for zero-overhead polymorphism |
| 109 | + |
| 110 | +## Documentation Structure |
| 111 | + |
| 112 | +### Core Documentation (docs/) |
| 113 | +- **getting_started.md**: 20-minute tutorial from installation to first working graph |
| 114 | +- **api.md**: Complete API reference covering all 21 header files |
| 115 | +- **architecture.md**: In-depth system design, template patterns, and implementation details |
| 116 | +- **advanced_features.md**: Custom costs, thread safety, performance optimization |
| 117 | +- **search_algorithms.md**: Comprehensive guide to A*, Dijkstra, BFS, DFS with examples |
| 118 | +- **real_world_examples.md**: Industry applications across gaming, robotics, GPS, networks |
| 119 | + |
| 120 | +### Tutorial Series (docs/tutorials/) |
| 121 | +- Progressive learning path from basic to advanced usage |
| 122 | +- Hands-on examples with complete working code |
| 123 | +- **01-basic-graph.md**: Fundamental operations |
| 124 | +- **02-pathfinding.md**: Search algorithms |
| 125 | +- **03-state-types.md**: Custom states and indexing |
| 126 | + |
| 127 | +### Supporting Documentation |
| 128 | +- **README.md**: Professional project overview with quick start |
| 129 | +- **index.md**: Documentation homepage for Doxygen integration |
| 130 | +- **doxygen/mainpage.md**: Main page for API documentation |
| 131 | + |
| 132 | +## Documentation Standards |
| 133 | + |
| 134 | +### File Naming Convention |
| 135 | +- Use **underscores** for documentation files (e.g., `getting_started.md`, `advanced_features.md`) |
| 136 | +- Maintain consistency across all documentation links |
| 137 | + |
| 138 | +### Content Guidelines |
| 139 | +- **Professional tone**: No emojis or casual language in technical documentation |
| 140 | +- **Complete code examples**: All code snippets must be compilable and working |
| 141 | +- **Progressive complexity**: Start simple, build to advanced concepts |
| 142 | +- **Real-world focus**: Emphasize practical applications and use cases |
| 143 | +- **Performance awareness**: Include complexity analysis and optimization guidance |
| 144 | + |
| 145 | +### Cross-Reference Standards |
| 146 | +- Link to related sections using relative paths |
| 147 | +- Maintain up-to-date cross-references between documentation files |
| 148 | +- Include file:line_number references for code locations when relevant |
| 149 | + |
| 150 | +## Sample Code Structure |
| 151 | + |
| 152 | +### Working Examples (sample/) |
| 153 | +- **simple_graph_demo.cpp**: Basic graph construction and pathfinding |
| 154 | +- **thread_safe_search_demo.cpp**: Concurrent search demonstrations |
| 155 | +- **lexicographic_cost_demo.cpp**: Multi-criteria optimization with custom cost types |
| 156 | +- **tuple_cost_demo.cpp**: std::tuple-based automatic lexicographic comparison |
| 157 | +- **incremental_search_demo.cpp**: Dynamic pathfinding scenarios |
| 158 | + |
| 159 | +### Code Quality Standards |
| 160 | +- All sample code must compile and run successfully |
| 161 | +- Include comprehensive error handling and validation |
| 162 | +- Demonstrate best practices for memory management and thread safety |
| 163 | +- Provide clear comments explaining design decisions and usage patterns |
0 commit comments