Add ADR 7: Tracker Service - Architecture changes for tracking performance scaling

[jdanieck]

📝 Description

Proposes pure C++ Tracker Service to meet current scale (1000 objects @ 4 cams @ 15 FPS) and future growth.

Architecture:

• Tracker Service (C++) - Real-time tracking with data-oriented design, SIMD, true paralelism.
• Analytics Service (Python) - Non-critical analytics.

Why: Current Python+pybind11 hits performance ceiling. C++ enables us to fully utilize the modern hardware.

Migration: Gradual rollout with feature flags (POC → MVP → production).

Related PRs

• [DO NOT MERGE] Tracker Service POC #614
• feature/spatial-analytics-documentation - Add spatial analytics developer guide #598
• Benchmark: JSON vs Protobuf Performance Analysis #636

✨ Type of Change

Select the type of change your PR introduces:

• 🐞 Bug fix – Non-breaking change which fixes an issue
• 🚀 New feature – Non-breaking change which adds functionality
• 🔨 Refactor – Non-breaking change which refactors the code base
• 💥 Breaking change – Changes that break existing functionality
• 📚 Documentation update
• 🔒 Security update
• 🧪 Tests
• 🚂 CI

🧪 Testing Scenarios

Describe how the changes were tested and how reviewers can test them too:

• ✅ Tested manually
• 🤖 Ran automated end-to-end tests

✅ Checklist

Before submitting the PR, ensure the following:

• 🔍 PR title is clear and descriptive
• 📝 For internal contributors: If applicable, include the JIRA ticket number (e.g., ITEP-123456) in the PR title. Do not include full URLs
• 💬 I have commented my code, especially in hard-to-understand areas
• 📄 I have made corresponding changes to the documentation
• ✅ I have added tests that prove my fix is effective or my feature works

[rawatts10]

Have we considered the overhead of additional serialization and deserialization of JSON over MQTT when adding an additional service? In fact, we could consider binary messaging (protobuf?) between all services, with only the analytics service outputting JSON for applications to consume on regulated, region, event, and related topics. Also, does it make sense to split the system into 3 services instead of 2? One for coordinate transforms/projection, one for tracking, and the last for analytics?

[saratpoluri]

Have we considered the overhead of additional serialization and deserialization of JSON over MQTT when adding an additional service? In fact, we could consider binary messaging (protobuf?) between all services, with only the analytics service outputting JSON for applications to consume on regulated, region, event, and related topics. Also, does it make sense to split the system into 3 services instead of 2? One for coordinate transforms/projection, one for tracking, and the last for analytics?

Don't want to consider the splitting of projection/transform from tracking at the moment. We should let the need dictate it. Once I implement the projection on terrain, we will know the overhead and the need for splitting.

[jdanieck]

@rawatts10 Have we considered the overhead of additional serialization and deserialization of JSON over MQTT when adding an additional service? In fact, we could consider binary messaging (protobuf?) between all services, with only the analytics service outputting JSON for applications to consume on regulated, region, event, and related topics. Also, does it make sense to split the system into 3 services instead of 2? One for coordinate transforms/projection, one for tracking, and the last for analytics?

@saratpoluri Don't want to consider the splitting of projection/transform from tracking at the moment. We should let the need dictate it. Once I implement the projection on terrain, we will know the overhead and the need for splitting.

My main assumption is that analytics can tolerate added latency compared to tracking, which has strict real-time requirements. The proposed split is effectively "real-time service" vs "near-real-time service."

If analytics also requires hard real-time guarantees, we should pursue Alternative 2: full C++ rewrite and keep it as a monolith. However, since we already have analytics in Python and it doesn't have the same latency constraints, we can start with this hybrid approach. If performance measurements later show Analytics becoming a bottleneck, we can incrementally migrate it to C++—a more manageable transition than rewriting everything upfront.

Regarding the processing volume: the Tracker Service handles significantly more data (1000 objects × 4 cameras × 15 FPS) than Analytics, which processes aggregated results. This asymmetry further supports the split architecture.

I agree that optimizing serialization/deserialization is worth investigating. I'll benchmark message encoding options (JSON vs Protobuf vs FlatBuffers) with 1k object payloads so we can make an informed decision based on actual performance data rather than assumptions.

[jdanieck]

@rawatts10 @saratpoluri completed serialization benchmarks for the Tracker/Analytics split in #636.

Good news: We can keep JSON initially. C++'s faster processing mostly compensates for the added MQTT hop - measured 6% improvement on localhost (1,370μs → 1,290μs per frame).

Migrating to Protobuf afterward would add 43% more through faster serialization and 29-63% smaller messages.

Proposed:

1. Split architecture with JSON first (simpler, validates architecture)
2. Migrate to Protobuf next (performance gains)

See ANALYSIS.md for details and RESULTS.md for raw benchmark data.

[jdanieck]

What's our policy on backward compatibility for inter-service communication? Can we make breaking changes to the message format?

[saratpoluri]

Right now, no policy. We make a breaking change if needed and let the users complain. In future, if we implement protobuf, then backward compatibility can be discussed.