# How Headroom's ContentRouter Manages and Routes Content Types for Optimal Compression

> Discover how Headroom's ContentRouter employs a three-phase pipeline to manage and route content types, enabling optimal compression strategies for efficient data handling.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-13

---

**Headroom's ContentRouter selects compression strategies through a three-phase pipeline that detects mixed-content documents, classifies pure content types using a Rust-based detector, and maps specific ContentType enums to specialized CompressionStrategy implementations.**

In the `chopratejas/headroom` repository, the **ContentRouter** serves as the intelligent traffic controller for compression operations. This component analyzes incoming payloads to determine whether they contain code, JSON, search results, or mixed formats, then routes each section to the appropriate compressor. Understanding how Headroom's ContentRouter manages and routes different content types reveals the architectural decisions that optimize compression ratios across diverse data formats.

## The Three-Phase Routing Architecture

The routing logic in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) follows a strict decision hierarchy implemented across three distinct phases.

### Phase 1: Mixed-Content Detection

Before attempting content classification, the router checks if the input contains multiple distinct formats. The `is_mixed_content()` function (lines 24-41) scans the document using four compiled regex patterns: `_CODE_FENCE_PATTERN`, `_JSON_BLOCK_START`, `_SEARCH_RESULT_PATTERN`, and `_PROSE_PATTERN`.

If at least two indicators trigger simultaneously, the router returns `CompressionStrategy.MIXED` and delegates to `_compress_mixed()`, which splits the document into sections using `split_into_sections()` and compresses each independently with its optimal strategy.

### Phase 2: Content-Type Classification

For non-mixed content, `_determine_strategy()` calls `_detect_content()` (lines 10-27) to identify the specific format. The implementation first attempts detection via the Rust-based `headroom._core.detect_content_type` binding. If this returns `plain_text`, the system falls back to `_regex_detect_content_type()` for lightweight pattern matching.

The result is a `ContentType` enum value defined in [`headroom/transforms/content_detector.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_detector.py), such as `SOURCE_CODE`, `JSON_ARRAY`, `SEARCH_RESULTS`, `BUILD_OUTPUT`, `GIT_DIFF`, `HTML`, or `PLAIN_TEXT`.

### Phase 3: Strategy Mapping and Selection

The final phase occurs in `_strategy_from_detection()` (lines 27-36), which translates `ContentType` enums into concrete implementations through a static mapping dictionary:

```python
mapping = {
    ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,
    ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,
    ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,
    ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,
    ContentType.GIT_DIFF: CompressionStrategy.DIFF,
    ContentType.HTML: CompressionStrategy.HTML,
    ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,
}

```

If the detected type lacks a specific mapping, the router uses `self.config.fallback_strategy`, which defaults to `CompressionStrategy.KOMPRESS`.

## Implementation Details and Source Code References

### Content Detection Deep Dive

The detection pipeline prioritizes performance through Rust integration. When `headroom._core.detect_content_type` returns a lowercase type tag, `_detect_content()` converts it to the corresponding Python enum member. This approach minimizes Python overhead for large payloads while maintaining accuracy through the regex fallback for edge cases.

### Strategy Resolution Logic

The `_determine_strategy()` method orchestrates the complete decision flow:

```python
if is_mixed_content(content):
    return CompressionStrategy.MIXED
detection = _detect_content(content)
return self._strategy_from_detection(detection)

```

Configuration flags can alter resolution logic. When `prefer_code_aware_for_code` is disabled, source code routes to `KOMPRESS` instead of `CODE_AWARE`, allowing users to bypass AST-aware processing when unnecessary.

### Fallback Chains and Error Handling

The `_apply_strategy_to_content()` method implements resilient fallback chains. If `CODE_AWARE` compression fails or is disabled, the router automatically attempts `KOMPRESS`. Similarly, `SMART_CRUSHER` failures cascade to the fallback strategy. Each routing decision is captured in a `RoutingDecision` object, with final results stored in `RouterCompressionResult` including the actually applied strategy.

## Configuration Options

Customize routing behavior through `ContentRouterConfig`:

- **enable_code_aware**: Toggle AST-aware compression for source code detection
- **fallback_strategy**: Default compressor when detection fails or mapping is undefined (default: `KOMPRESS`)
- **prefer_code_aware_for_code**: Prefer `CODE_AWARE` over `KOMPRESS` for detected code types

## Practical Code Examples

### Basic Content Routing

```python
from headroom.transforms import ContentRouter

router = ContentRouter()

# JSON payload automatically routes to SmartCrusher

json_data = '[{"id":1,"value":"compress me"}]'
result = router.compress(json_data)
print(result.strategy_used)  # CompressionStrategy.SMART_CRUSHER

```

### Handling Mixed Documents

```python
mixed_doc = """

# Configuration

```json
{"setting": "value"}

```

Explanation text follows.
"""

result = router.compress(mixed_doc)
print(result.strategy_used)  # CompressionStrategy.MIXED

print(result.routing_log)    # List of RoutingDecision objects per section

```

### Custom Configuration

```python
from headroom.transforms import ContentRouter, ContentRouterConfig, CompressionStrategy

config = ContentRouterConfig(
    enable_code_aware=False,
    fallback_strategy=CompressionStrategy.TEXT
)
router = ContentRouter(config=config)

# Forces TEXT strategy for plain content instead of KOMPRESS

result = router.compress("Simple text document")

```

## Summary

- **ContentRouter** analyzes all payloads through `is_mixed_content()` before attempting type-specific detection
- **Mixed documents** split into sections and route individually via `CompressionStrategy.MIXED`
- **Pure content** flows through Rust-based detection (`headroom._core.detect_content_type`) with regex fallback in `_detect_content()`
- **Strategy mapping** uses a static dictionary linking `ContentType` enums to `CompressionStrategy` implementations in `_strategy_from_detection()`
- **Fallback chains** ensure compression succeeds even when preferred strategies fail or are disabled
- **Configuration** via `ContentRouterConfig` controls code-aware preferences and default fallback behavior

## Frequently Asked Questions

### What happens when ContentRouter encounters unrecognized content?

When detection returns an unmapped type or the Rust detector fails, the router defaults to `self.config.fallback_strategy`, which is `CompressionStrategy.KOMPRESS` unless explicitly configured otherwise. This ensures all payloads receive compression even when type classification is uncertain or ambiguous.

### How does ContentRouter handle documents containing both code and prose?

The `is_mixed_content()` function identifies these documents by scanning for multiple pattern indicators including code fences, JSON blocks, search results, and prose sections. When mixed content is detected, the router applies `CompressionStrategy.MIXED`, splits the document using `split_into_sections()`, and routes each section to its optimal compressor individually, preserving format-specific optimizations.

### Can I force ContentRouter to use a specific compression strategy?

While ContentRouter is designed for automatic selection, you can influence outcomes through configuration. Set `enable_code_aware=False` to force code payloads toward `KOMPRESS`, or adjust `fallback_strategy` to change the default catch-all. However, for explicit strategy selection, instantiate specific compressors directly rather than using the router, as the router's purpose is intelligent routing based on content analysis.

### What telemetry does ContentRouter provide for routing decisions?

After compression, `_record_to_toin()` logs the operation to the TOIN telemetry system, except for `SMART_CRUSHER` operations which self-record. The `RouterCompressionResult` object contains `routing_log` with `RoutingDecision` entries detailing which strategy was selected, whether fallback chains were invoked, and which compressor ultimately processed the content.