docs: simplify and realign repository documentation

Author: argahsuknesib

GETTING_STARTED.md

@@ -1,79 +1,102 @@
 # Janus
 
-Janus is a hybrid engine for unified Live and Historical RDF Stream Processing, implemented in Rust.
+Janus is a Rust engine for hybrid RDF stream processing. It combines:
 
-The name "Janus" is inspired by the Roman deity Janus who is the guardian of doorways and transitions, and looks towards both the past and the future simultaneously. This dual perspective reflects Janus's capability to process both Historical and Live RDF streams in a unified manner utilizing a single query language and engine.
+- historical query execution over locally stored RDF events
+- live query execution over streaming RDF data
+- a JanusQL parser that lowers hybrid queries to SPARQL and RSP-QL
+- an HTTP/WebSocket API for query management and result streaming
 
-## Performance
+## Repository Status
 
-Janus achieves high-throughput RDF stream processing with dictionary encoding and streaming segmented storage:
+The backend repository is active and locally healthy:
 
-- Write Throughput: 2.6-3.14 Million quads/sec
-- Read Throughput: 2.7-2.77 Million quads/sec
-- Point Query Latency: Sub-millisecond (0.235 ms at 1M quads)
-- Space Efficiency: 40% reduction through dictionary encoding (24 bytes vs 40 bytes per event)
+- `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
 
-For detailed benchmark results, see [BENCHMARK_RESULTS.md](./BENCHMARK_RESULTS.md).
+This repository is the backend and engine implementation.
 
-## Development
+The maintained dashboard lives in a separate repository:
+- `https://github.com/SolidLabResearch/janus-dashboard`
 
-### Prerequisites
+The `janus-dashboard/` folder in this repository is a lightweight local demo client, not the primary frontend.
 
-- Rust (stable toolchain)
-- Cargo
+## What You Can Run
 
-### Building
+### HTTP API server
 
 ```bash
-# Debug build
-make build
+cargo run --bin http_server
+```
 
-# Release build (optimized)
-make release
+This starts the backend on `http://127.0.0.1:8080` by default.
+
+### Stream replay / ingestion CLI
+
+```bash
+cargo run --bin stream_bus_cli -- --help
 ```
 
-### Testing
+Use this to replay RDF input files into storage and optionally publish them to MQTT.
+
+### Tests
 
 ```bash
-# Run all tests
 make test
+```
+
+### Linting
 
-# Run tests with verbose output
-make test-verbose
+```bash
+make lint
 ```
 
-### Code Quality
+## Development
 
-Before pushing to the repository, run the CI/CD checks locally:
+### Prerequisites
 
-```bash
-# Run all CI/CD checks (formatting, linting, tests, build)
-make ci-check
+- Rust stable
+- Cargo
+- Docker, if you want to run the local MQTT broker from `docker-compose.yml`
 
-# Or use the script directly
-   ./scripts/ci-check.sh```
+### Build
 
-This will run:
-- **rustfmt** - Code formatting check
-- **clippy** - Lint checks with warnings as errors
-- **tests** - Full test suite
-- **build** - Compilation check
+```bash
+make build
+make release
+```
 
-Individual checks can also be run:
+### Full local CI checks
 
 ```bash
-make fmt        # Format code
-make fmt-check  # Check formatting
-make lint       # Run Clippy
-make check      # Run formatting and linting checks
+make ci-check
 ```
 
-## Licence 
+This runs formatting, clippy, tests, and build checks.
 
-This code is copyrighted by Ghent University - imec and released under the MIT Licence
+## Documentation
 
-## Contact
+Start here:
 
-For any questions, please contact [Kush](mailto:mailkushbisen@gmail.com) or create an issue in the repository.
+- [GETTING_STARTED.md](./GETTING_STARTED.md)
+- [START_HERE.md](./START_HERE.md)
+- [docs/README.md](./docs/README.md)
+- [docs/README_HTTP_API.md](./docs/README_HTTP_API.md)
+
+Performance notes:
+
+- [docs/BENCHMARK_RESULTS.md](./docs/BENCHMARK_RESULTS.md)
+
+## Notes
+
+- `src/main.rs` is currently a benchmark-style executable, not the main user-facing interface.
+- The primary user-facing entry point is `http_server`.
+
+## Licence
+
+This code is copyrighted by Ghent University - imec and released under the MIT Licence.
+
+## Contact
 
----
+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

@@ -1,87 +1,31 @@
-# Janus HTTP API - Documentation Index
+# Janus Documentation Index
 
-## Getting Started
+## Canonical Entry Points
 
-1. **START_HERE.md** - 🚀 BEGIN HERE - Quick start guide
-2. **scripts/test_setup.sh** - Automated setup script
-3. **docker-compose.yml** - MQTT broker configuration
+- [../README.md](../README.md)
+- [../GETTING_STARTED.md](../GETTING_STARTED.md)
+- [../START_HERE.md](../START_HERE.md)
+- [README_HTTP_API.md](README_HTTP_API.md)
+- [QUICKSTART_HTTP_API.md](QUICKSTART_HTTP_API.md)
 
-## Quick Reference
+## Backend Guides
 
-4. **QUICK_REFERENCE.md** - One-page cheat sheet
-5. **FINAL_TEST.md** - Test verification steps
-6. **RUNTIME_FIX_SUMMARY.md** - Runtime panic fix explanation
+- [STREAM_BUS_CLI.md](STREAM_BUS_CLI.md)
+- [HTTP_API.md](HTTP_API.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [EXECUTION_ARCHITECTURE.md](EXECUTION_ARCHITECTURE.md)
+- [BENCHMARK_RESULTS.md](BENCHMARK_RESULTS.md)
 
-## Complete Guides
+## Historical Context
 
-7. **SETUP_GUIDE.md** - Comprehensive setup with MQTT
-8. **README_HTTP_API.md** - Complete API documentation  
-9. **COMPLETE_SOLUTION.md** - Full implementation details
-10. **HTTP_API_IMPLEMENTATION.md** - Technical architecture
+The files below are retained for implementation history and design context. Some of them describe earlier states of the project and should not be treated as the current source of truth:
 
-## Code
+- [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)
 
-11. **src/http/server.rs** - HTTP server implementation (537 lines)
-12. **src/http/mod.rs** - Module exports
-13. **src/bin/http_server.rs** - Server binary (111 lines)
-14. **examples/http_client_example.rs** - Client example (370 lines)
-15. **examples/demo_dashboard.html** - Interactive dashboard (670 lines)
+## Dashboard Boundary
 
-## Configuration
-
-16. **docker/mosquitto/config/mosquitto.conf** - MQTT broker config
-17. **Cargo.toml** - Dependencies (axum, tower-http, tokio-tungstenite, etc.)
-
-## How to Use This Documentation
-
-### If you're brand new:
-→ Read **START_HERE.md**
-
-### If you want quick commands:
-→ Read **QUICK_REFERENCE.md**
-
-### If you see runtime panics:
-→ Read **RUNTIME_FIX_SUMMARY.md**
-
-### If you need detailed setup:
-→ Read **SETUP_GUIDE.md**
-
-### If you want to understand the API:
-→ Read **README_HTTP_API.md**
-
-### If you need implementation details:
-→ Read **COMPLETE_SOLUTION.md** or **HTTP_API_IMPLEMENTATION.md**
-
-### If you want to verify everything works:
-→ Follow **FINAL_TEST.md**
-
-## File Sizes
-
-```
-START_HERE.md                    ~1 KB   (Quick start)
-QUICK_REFERENCE.md               ~2 KB   (Cheat sheet)
-RUNTIME_FIX_SUMMARY.md           ~3 KB   (Fix explanation)
-FINAL_TEST.md                    ~3 KB   (Testing guide)
-SETUP_GUIDE.md                   ~18 KB  (Detailed setup)
-README_HTTP_API.md               ~15 KB  (API guide)
-COMPLETE_SOLUTION.md             ~9 KB   (Solution summary)
-HTTP_API_IMPLEMENTATION.md       ~19 KB  (Technical details)
-
-src/http/server.rs               ~15 KB  (Server code)
-examples/demo_dashboard.html     ~20 KB  (Dashboard)
-examples/http_client_example.rs  ~11 KB  (Client example)
-```
-
-## Priority Reading Order
-
-1. START_HERE.md
-2. QUICK_REFERENCE.md
-3. SETUP_GUIDE.md (if needed)
-4. README_HTTP_API.md (for API details)
-
-The rest are reference materials for specific needs.
-
----
-
-**Total: ~115 KB of documentation + ~50 KB of code**  
-**Everything you need to use Janus HTTP API successfully!**
+- Local demo dashboard in this repository: `examples/demo_dashboard.html`
+- Maintained dashboard repository: `https://github.com/SolidLabResearch/janus-dashboard`