Understand the Framework

This article walks through the model we've built into the troubleshooting documentation. The goal is to give you a consistent framework for understanding the solution—not just a list of commands, but a way of thinking about the system.

Setting the stage: Before diving into specifics, here's a quick snapshot.

"Kubernetes-based platform with 60+ microservices that collects telemetry from sensors, processes it through a streaming pipeline, and serves insights via web UI and APIs."

The healthy state in one sentence:

• All pods running ✓

• Data flows sensor-to-UI in ~10 seconds ✓

• Users can log in and see current metrics ✓

Three Questions Framework

The diagnostic starting point: We propose three questions to help you quickly isolate the problem domain.

The logic:

• If login fails → Focus on Presentation Plane (Zitadel, PostgreSQL)

• If data is missing → Focus on Data Plane (Kafka, Ignite, Druid)

• If pods are down → Focus on Infrastructure (resources, PVCs, configs)

Three Planes Architecture

Organizing 60+ services: We group services into three logical planes to make the system comprehensible.

Presentation Plane (User-Facing)

This is what you and your users interact with directly. When someone reports they "can't access the system" or "the UI is broken," start here. These services handle authentication, serve the web interface, and expose APIs.

Data Plane (Telemetry Processing)

This is where the real work happens. Sensor data flows through these services to be ingested, processed, and stored. When users report "missing data," "stale metrics," or "dashboards not updating," you'll be investigating this plane.

Control Plane (Configuration)

These services manage how the platform is configured and how sensors are orchestrated. Issues here are often more subtle—sensors failing to register, configuration changes not taking effect, or tenant-specific problems. Check this plane when the system is "running" but not behaving as expected.

Data Flow Visualization

Tracing the happy path: We show how data moves through the system so you can trace backwards when something breaks.

Sensor → RoadRunner → Fedex → Kafka → Ignite → Druid → Gather → UI

Key insight: When data is missing, trace backwards:

1. Is Druid ingesting? (Check supervisor status)

2. Is Kafka flowing? (Check consumer lag)

3. Is RoadRunner receiving? (Check pod logs)

4. Is the sensor connected? (Check sensor status)

Expected latency: ~10 seconds end-to-end

Common Scenarios Mapping

Quick lookup: We map common symptoms to likely causes and first checks.

Reference: Full Documentation Set

The following guides provide detailed procedures for each area covered in this overview. Use them as your go-to references when you need step-by-step instructions or deeper technical detail.