docs: add research metrics and stabilize repo quality

[CoreyLeath-code]

Root cause

• The README had stale repository references, mojibake/corrupted sections, an unclosed code fence, and benchmark claims that did not distinguish measured local results from production targets.
• The Python test suite could not collect because several tests imported non-importable hyphenated module paths and referenced missing packages/modules.
• CI workflows masked real failures with || echo, used stale dependency/cache inputs, and the CD workflow referenced nonexistent service Dockerfiles.

Changes

• Replaced the README with a clean research-style architecture, benchmark, quality metrics, validation, and industry-readiness section.
• Added deterministic benchmark coverage via benchmarks/ride_sharing_benchmarks.py and recorded benchmark-results.json.
• Repaired core imports and timezone helpers so the event bus, matching engine, driver store, pricing engine, and app entrypoints are importable.
• Replaced placeholder/broken tests with behavior tests for event bus publish/subscribe, no-subscriber safety, driver store operations, matching rank/selection, and pricing surge behavior.
• Added pyproject.toml, requirements.txt, updated dev requirements, removed the stale generated dev lock, and added Makefile install/benchmark targets.
• Hardened GitHub Actions: real pip caching, committed dependency installation, black/ruff/mypy/pytest gates, benchmark JSON validation, benchmark artifacts, workflow summaries, current action versions, and valid Docker build inputs.

Validation

• black --check . --line-length 100
• ruff check .
• pytest -q --cov=. --cov-report=term-missing
  • 8 passed
  • 54% current coverage, honestly recorded in README
• mypy models.py utils.py event_bus.py location_store.py matching_engine.py pricing_engine.py consumer.py --ignore-missing-imports
• python benchmarks/ride_sharing_benchmarks.py --iterations 500 --driver-count 100 --output benchmark-results.json
• python -m json.tool benchmark-results.json
• python -m compileall -q shared services
• git diff --check

Screenshots

Not applicable; documentation, CI, benchmark, and Python quality changes only.

Summary by CodeRabbit

• New Features

  • Added repeatable performance benchmarks covering event processing, matching, location storage, and pricing.
  • Added benchmark result validation and downloadable reports.
  • Improved deployment summaries with published container image details.

• Bug Fixes

  • Improved event delivery reliability when notifying multiple subscribers.
  • Standardized timestamps as timezone-aware UTC values.
  • Improved driver-location data handling and validation.

• Documentation

  • Reworked the README with architecture guidance, setup instructions, validation steps, benchmarks, and known limitations.

• Chores

  • Strengthened automated formatting, linting, type checking, testing, coverage, and security checks.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e6b4d9fd-0756-47c1-9f49-6798a9879934

📥 Commits

Reviewing files that changed from the base of the PR and between 72b5ac9 and 462d230.

⛔ Files ignored due to path filters (1)

• requirements-dev.lock is excluded by !**/*.lock

📒 Files selected for processing (40)

• .github/workflows/cd.yml
• .github/workflows/ci.yml
• .github/workflows/hygiene-matrix.yml
• .gitignore
• Makefile
• README.md
• api_router.py
• benchmark-results.json
• benchmarks/ride_sharing_benchmarks.py
• consumer.py
• event_bus.py
• kafka_bus.py
• load-tests/locustfile.py
• location_store.py
• main.py
• matching_engine.py
• models.py
• pricing_engine.py
• pyproject.toml
• rabbitmq_bus.py
• redis_bus.py
• requirements-dev.txt
• requirements.txt
• services/api-gateway/main.py
• services/matching-service/main.py
• shared/config.py
• shared/database/db.py
• shared/event_bus/kafka_consumer.py
• shared/event_bus/kafka_producer.py
• shared/event_schema/ride_events.py
• shared/logging_config.py
• src/event-bus/base.py
• src/pricing-service/__init__.py
• src/pricing-service/main.py
• test_dispatch_engine.py
• test_driver_location_store.py
• test_event_bus.py
• tests/test_matching_service.py
• tests/test_pricing_engine.py
• utils.py

---

📝 Walkthrough

Walkthrough

The pull request updates CI/CD workflows, adds benchmark tooling and outputs, standardizes Python module imports and typing, adjusts event-bus and service startup behavior, expands behavioral tests, and rewrites project documentation.

Changes

Platform validation and runtime updates

Layer / File(s)	Summary
Workflow and development tooling .github/workflows/*, Makefile, pyproject.toml, requirements*.txt, .gitignore	Workflows now run formatting, linting, type checking, coverage, benchmarks, artifact validation, and container publishing with updated permissions and actions.
Benchmark harness and recorded output benchmarks/ride_sharing_benchmarks.py, benchmark-results.json	A CLI benchmark runner measures event bus, matching, location storage, and pricing performance and writes aggregated JSON results.
Application module paths and service wiring api_router.py, main.py, location_store.py, matching_engine.py, pricing_engine.py, utils.py, src/pricing-service/*, services/*	Imports use top-level modules, location-store methods gain typing, timestamps become timezone-aware, and service startup wiring is simplified or redirected.
Event-bus and shared runtime behavior event_bus.py, kafka_bus.py, rabbitmq_bus.py, redis_bus.py, shared/*, src/event-bus/base.py	Subscriber callbacks are snapshotted before concurrent dispatch, Kafka publishing flushes explicitly, and shared configuration and adapter formatting are updated.
Behavioral test coverage test_*.py, tests/*	Tests now cover matching order and selection, location-store CRUD behavior, event-bus empty-topic safety, and pricing surge calculations.
Documentation and load-test alignment README.md, load-tests/locustfile.py	README architecture, validation, benchmark, setup, structure, and readiness content was rewritten; the load-test request payload formatting was updated without changing its data.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant BenchmarkRunner
  participant EventBus
  participant MatchingEngine
  participant DriverLocationStore
  participant PricingEngine
  participant ArtifactStore
  CI->>BenchmarkRunner: Run benchmark command
  BenchmarkRunner->>EventBus: Measure event publishing
  BenchmarkRunner->>MatchingEngine: Measure driver selection
  BenchmarkRunner->>DriverLocationStore: Measure location upserts
  BenchmarkRunner->>PricingEngine: Measure surge computation
  BenchmarkRunner-->>CI: Produce benchmark-results.json
  CI->>ArtifactStore: Validate and upload JSON artifact

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/research-metrics-industry-readiness

---

_{Comment @coderabbitai help to get the list of available commands.}