Merge pull request #16 from SolidLabResearch/codex/docs-sync

docs: simplify and realign repository documentation

Author: argahsuknesib

GETTING_STARTED.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
 
@@ -128,23 +145,26 @@ make ci-check      # local CI script
 The repository includes runnable examples under [`examples/`](./examples), including:
 
 - [`examples/http_client_example.rs`](./examples/http_client_example.rs)
-- [`examples/comparator_demo.rs`](./examples/comparator_demo.rs)
-- [`examples/demo_dashboard.html`](./examples/demo_dashboard.html)
 
-## 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.

README.md

@@ -1,75 +1,54 @@
-# Janus HTTP API - START HERE
+# Janus Backend - Start Here
 
-## Quick Start (30 seconds)
+Use this file if you want the fastest path to a working local backend.
 
-```bash
-# 1. Setup (one time)
-   ./scripts/test_setup.sh
-# 2. Start MQTT
-docker-compose up -d mosquitto
+## Quick Start
 
-# 3. Start Server
-cargo run --bin http_server
+### 1. Start the MQTT broker
 
-# 4. Open Dashboard
-open examples/demo_dashboard.html
+```bash
+docker-compose up -d mosquitto
 ```
 
-Then click: **Start Replay** → **Start Query**
-
-## What This Does
+### 2. Start the HTTP server
 
-1. **Start Replay**: Loads RDF data from `data/sensors.nq`, publishes to MQTT, stores locally
-2. **Start Query**: Executes a JanusQL query, streams results via WebSocket to dashboard
+```bash
+cargo run --bin http_server
+```
 
-## Documentation
+### 3. Check health
 
-- **QUICK_REFERENCE.md** - One-page cheat sheet
-- **RUNTIME_FIX_SUMMARY.md** - How the runtime issue was fixed
-- **COMPLETE_SOLUTION.md** - Full implementation details
-- **SETUP_GUIDE.md** - Detailed setup instructions
-- **README_HTTP_API.md** - Complete API documentation
-- **FINAL_TEST.md** - Verification steps
+```bash
+curl http://localhost:8080/health
+```
 
-## Key Points
+Expected response:
 
-✅ **No more runtime panics** - Fixed by spawning StreamBus in separate thread  
-✅ **Correct JanusQL syntax** - All examples updated to match parser  
-✅ **MQTT integration** - Full broker setup with Docker Compose  
-✅ **Two-button demo** - Interactive dashboard for easy testing  
-✅ **Production-ready** - Stable, tested, documented  
+```json
+{"message":"Janus HTTP API is running"}
+```
 
-⚠️ **Known limitation**: Replay metrics show status but not event counts (acceptable trade-off)
+## Optional: Open the local demo dashboard
 
-## Troubleshooting
+This repository contains a small demo dashboard:
 
 ```bash
-# Server won't start (port in use)
-lsof -ti:8080 | xargs kill -9
-
-# MQTT not running
-docker-compose up -d mosquitto
-
-# Check if working
-curl http://localhost:8080/health
+open examples/demo_dashboard.html
 ```
 
-## Success Indicators
+For the maintained frontend, use the separate repository:
 
-When everything works correctly:
-1. Server starts with clean output (no panics)
-2. Dashboard shows "Connected to Janus HTTP API server"  
-3. Replay button → Status changes to "Running"
-4. Query button → WebSocket connects, results appear
-5. Results tagged as "historical" or "live"
+- `https://github.com/SolidLabResearch/janus-dashboard`
 
-## Need Help?
+## Most Useful Docs
 
-1. Read **QUICK_REFERENCE.md** for common commands
-2. Check **FINAL_TEST.md** for verification steps
-3. See **RUNTIME_FIX_SUMMARY.md** if you see panics
-4. Review **SETUP_GUIDE.md** for detailed instructions
+- [GETTING_STARTED.md](./GETTING_STARTED.md)
+- [docs/README_HTTP_API.md](./docs/README_HTTP_API.md)
+- [docs/QUICKSTART_HTTP_API.md](./docs/QUICKSTART_HTTP_API.md)
+- [docs/README.md](./docs/README.md)
 
----
+## Notes
 
-**Everything is ready. Just run the Quick Start commands above!** 🚀
+- The backend is the primary concern of this repository.
+- `http_server` is the main user-facing executable.
+- `stream_bus_cli` is the replay/ingestion CLI.

START_HERE.md

@@ -5,11 +5,13 @@ This is the shortest path to understanding the current Janus implementation.
 ## Core Reading Order
 
 1. [../README.md](../README.md)
-2. [JANUSQL.md](./JANUSQL.md)
-3. [QUERY_EXECUTION.md](./QUERY_EXECUTION.md)
-4. [BASELINES.md](./BASELINES.md)
-5. [HTTP_API_CURRENT.md](./HTTP_API_CURRENT.md)
-6. [ANOMALY_DETECTION.md](./ANOMALY_DETECTION.md)
+2. [../GETTING_STARTED.md](../GETTING_STARTED.md)
+3. [../START_HERE.md](../START_HERE.md)
+4. [JANUSQL.md](./JANUSQL.md)
+5. [QUERY_EXECUTION.md](./QUERY_EXECUTION.md)
+6. [BASELINES.md](./BASELINES.md)
+7. [HTTP_API_CURRENT.md](./HTTP_API_CURRENT.md)
+8. [ANOMALY_DETECTION.md](./ANOMALY_DETECTION.md)
 
 ## What Each File Covers
 
@@ -43,15 +45,29 @@ This is the shortest path to understanding the current Janus implementation.
   - when baseline state helps
   - recommended query patterns
 
+## 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)
+- [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)
+
 ## Legacy Material
 
 The following files remain useful as background, but they are not the main entrypoint for the current code:
 
 - [ARCHITECTURE.md](./ARCHITECTURE.md)
 - [EXECUTION_ARCHITECTURE.md](./EXECUTION_ARCHITECTURE.md)
 - [HTTP_API.md](./HTTP_API.md)
-- [README_HTTP_API.md](./README_HTTP_API.md)
-- [SETUP_GUIDE.md](./SETUP_GUIDE.md)
+- [MVP_TODO.md](./MVP_TODO.md)
+- [MVP_ARCHITECTURE.md](./MVP_ARCHITECTURE.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