Merge origin/main into codex/repo-hardening

Author: argahsuknesib

GETTING_STARTED.md

@@ -84,143 +84,3 @@ make ci-check
 - `README.md`
 - `START_HERE.md`
 - `docs/DOCUMENTATION_INDEX.md`
-
-## Common Rust Commands
-
-Here are some useful Cargo commands:
-
-```bash
-# Build the project
-cargo build
-
-# Build with optimizations
-cargo build --release
-
-# Run the binary
-cargo run
-
-# Run with arguments
-cargo run -- --help
-
-# Run tests
-cargo test
-
-# Run a specific test
-cargo test test_name
-
-# Run examples
-cargo run --example basic
-
-# Generate documentation
-cargo doc --open
-
-# Check code without building
-cargo check
-
-# Update dependencies
-cargo update
-
-# Show dependency tree
-cargo tree
-
-# Clean build artifacts
-cargo clean
-```
-
-## Using Rust Analyzer
-
-For the best development experience, install Rust Analyzer in your editor:
-
-- **VS Code**: Install the "rust-analyzer" extension
-- **IntelliJ/CLion**: Rust plugin comes with IntelliJ Rust
-- **Vim/Neovim**: Use rust-analyzer with LSP plugins
-- **Emacs**: Use lsp-mode with rust-analyzer
-
-## Next Steps
-
-Now that you have Janus set up, here's what you can do next:
-
-1. **Explore the Architecture**: Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand the design
-2. **Read the Contributing Guide**: Check [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
-3. **Start Implementing**: Begin with one of the TODO items in the roadmap
-4. **Write Tests**: Add tests for any new functionality
-5. **Improve Documentation**: Help improve docs and examples
-
-## Common Issues
-
-### Issue: Rust not found
-
-**Solution**: Ensure Rust is installed and in your PATH. Restart your terminal after installation.
-
-### Issue: Docker containers fail to start
-
-**Solution**: Check if ports 7878 and 3030 are already in use:
-
-```bash
-lsof -i :7878
-lsof -i :3030
-```
-
-### Issue: Tests failing
-
-**Solution**: Make sure all dependencies are up to date:
-
-```bash
-cargo update
-cargo build
-cargo test
-```
-
-### Issue: Compilation errors
-
-**Solution**: Clean the build and rebuild:
-
-```bash
-cargo clean
-cargo build
-```
-
-## Learning Resources
-
-### Rust
-
-- [The Rust Book](https://doc.rust-lang.org/book/)
-- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)
-- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
-
-### RDF and SPARQL
-
-- [RDF Primer](https://www.w3.org/TR/rdf11-primer/)
-- [SPARQL Tutorial](https://www.w3.org/TR/sparql11-query/)
-- [RSP-QL Specification](https://streamreasoning.org/RSP-QL/)
-
-### Stream Processing
-
-- [Stream Processing Concepts](https://www.oreilly.com/library/view/streaming-systems/9781491983867/)
-- [RDF Stream Processing](https://streamreasoning.org/)
-
-## Getting Help
-
-If you need help:
-
-1. **Check the documentation**: Read the existing docs and code comments
-2. **Search issues**: Look for similar issues on GitHub
-3. **Open an issue**: Create a new issue with details about your problem
-4. **Contact maintainers**: Email [mailkushbisen@gmail.com](mailto:mailkushbisen@gmail.com)
-
-## Contributing
-
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
-
-- How to submit pull requests
-- Coding standards
-- Testing requirements
-- Review process
-
-## License
-
-This project is licensed under the MIT License - see [LICENCE.md](LICENCE.md) for details.
-
----
-
-Happy coding with Janus!

README.md

@@ -56,6 +56,22 @@ WHERE {
 - `LAST`: use the final historical window snapshot as baseline
 - `AGGREGATE`: merge the historical window outputs into one compact baseline
 
+## Repository Status
+
+The backend repository is active and locally healthy:
+
+- `cargo test --all-features` passes
+- `cargo clippy --all-targets --all-features -- -D warnings` passes
+- the HTTP API, Janus API, parser, storage layer, and stream bus all have integration coverage
+
+This repository is the backend and engine implementation.
+
+The maintained dashboard lives in a separate repository:
+
+- `https://github.com/SolidLabResearch/janus-dashboard`
+
+The `janus-dashboard/` folder in this repository is a lightweight local demo client, not the primary frontend.
+
 ## Performance
 
 Janus uses dictionary encoding and segmented storage for high-throughput ingestion and historical reads.
@@ -65,14 +81,15 @@ Janus uses dictionary encoding and segmented storage for high-throughput ingesti
 - Point query latency: 0.235 ms at 1M quads
 - Space efficiency: about 40% smaller encoded events
 
-Detailed benchmark data is in [BENCHMARK_RESULTS.md](./BENCHMARK_RESULTS.md).
+Detailed benchmark data is in [docs/BENCHMARK_RESULTS.md](./docs/BENCHMARK_RESULTS.md).
 
 ## Quick Start
 
 ### Prerequisites
 
 - Rust stable
 - Cargo
+- Docker, if you want to run the local MQTT broker from `docker-compose.yml`
 
 ### Build
 
@@ -140,20 +157,25 @@ The repository includes runnable examples under [`examples/`](./examples), inclu
 - [`examples/comparator_demo.rs`](./examples/comparator_demo.rs)
 - [`examples/demo_dashboard.html`](./examples/demo_dashboard.html) for a minimal local demo
 
-## Project Layout
+## Documentation
+
+Start here:
+
+- [GETTING_STARTED.md](./GETTING_STARTED.md)
+- [START_HERE.md](./START_HERE.md)
+- [docs/DOCUMENTATION_INDEX.md](./docs/DOCUMENTATION_INDEX.md)
+- [docs/README.md](./docs/README.md)
+- [docs/HTTP_API_CURRENT.md](./docs/HTTP_API_CURRENT.md)
+
+## Notes
 
-- [`src/api`](./src/api): query lifecycle and orchestration
-- [`src/parsing`](./src/parsing): Janus-QL parsing
-- [`src/stream`](./src/stream): live stream processing
-- [`src/execution`](./src/execution): historical execution
-- [`src/storage`](./src/storage): segmented RDF storage
-- [`src/http`](./src/http): REST and WebSocket API
-- [`tests`](./tests): integration and parser coverage
+- `src/main.rs` is currently a benchmark-style executable, not the main user-facing interface.
+- The primary user-facing entry point is `http_server`.
 
-## License
+## Licence
 
-This project is released under the MIT License.
+This code is copyrighted by Ghent University - imec and released under the MIT Licence.
 
 ## Contact
 
-For questions, open an issue or contact [Kush](mailto:mailkushbisen@gmail.com).
+For questions, contact [Kush](mailto:mailkushbisen@gmail.com) or open an issue in the repository.

START_HERE.md

@@ -27,4 +27,6 @@ cargo run --example http_client_example
 - `GETTING_STARTED.md`
 - `docs/DOCUMENTATION_INDEX.md`
 - `docs/HTTP_API_CURRENT.md`
+- `docs/README_HTTP_API.md`
+- `docs/QUICKSTART_HTTP_API.md`
 - `docs/QUICK_REFERENCE.md`

docs/DOCUMENTATION_INDEX.md

@@ -52,6 +52,12 @@ This is the shortest path to understanding the current Janus implementation.
   - replay endpoints
   - smoke-test flow
 
+## Additional Current Guides
+
+- [STREAM_BUS_CLI.md](./STREAM_BUS_CLI.md)
+- [README_HTTP_API.md](./README_HTTP_API.md)
+- [QUICKSTART_HTTP_API.md](./QUICKSTART_HTTP_API.md)
+
 ## Legacy Material
 
 The following files remain useful as background, but they are not the main entrypoint for the current code:
@@ -60,6 +66,13 @@ The following files remain useful as background, but they are not the main entry
 - [EXECUTION_ARCHITECTURE.md](./EXECUTION_ARCHITECTURE.md)
 - [MVP_ARCHITECTURE.md](./MVP_ARCHITECTURE.md)
 - [MVP_TODO.md](./MVP_TODO.md)
+- [RSP_INTEGRATION_COMPLETE.md](./RSP_INTEGRATION_COMPLETE.md)
+- [SPARQL_BINDINGS_UPGRADE.md](./SPARQL_BINDINGS_UPGRADE.md)
+
+## Dashboard Boundary
+
+- Local demo dashboard in this repository: `examples/demo_dashboard.html`
+- Maintained dashboard repository: `https://github.com/SolidLabResearch/janus-dashboard`
 
 ## Related Code