architecture

Documents the C++ core architecture of the strata JSON engine for contributors.

Updated Nov 20, 2025
One-click install
npx skills add https://github.com/PrimeLab-Foundation/strata --skill architecture-primelab-foundation
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architecture
Source: https://github.com/PrimeLab-Foundation/strata/tree/main/docs/architecture
Command: npx skills add https://github.com/PrimeLab-Foundation/strata --skill architecture-primelab-foundation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Contributors modifying strata's C++ core need a single authoritative map of its parser, DOM, serializers, NDJSON, mmap, error and memory models, plus the invariants and dead code that must not be built upon. ## Core Features & Use Cases - Hybrid SAX parser blueprint: Explains the templated ParserInline design, tiered double conversion (Clinger, Eisel-Lemire, from_chars), SIMD string scanning, and speculative key matching. - Serialization and value model reference: Covers the two independent serialize paths, the FlatMap-based JsonValue DOM, NDJSON streaming, and the mmap cursor footguns. - Contributor invariants and dead-code map: Nine enforced invariants (nesting cap, cursor ownership, thread-local settings) plus an explicit list of dead functions that must not be reused. - Use Case: Before editing anything under include/strata/ or src/strata/{json,search,util}, load this Skill to understand which behaviors are pinned by test and which files are safe to change. ## Quick Start Load the architecture skill before modifying any C++ file under include/strata or src/strata to review the relevant invariants and design decisions.

Frequently Asked Questions about architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How does the strata C++ parser achieve its performance?

The parser uses a templated ParserInline that devirtualizes SAX callbacks, tiered double conversion (Clinger, Eisel-Lemire, from_chars), SIMD whitespace and escape scanning, and zero-copy string_views for escape-free strings. Speculative key matching lets handlers consume raw key bytes before escape scanning.

What is the maximum JSON nesting depth in strata?

Nesting is capped at 1024 open containers via strata::kMaxNestingDepth, enforced in ParserInline before the handler sees the container. Exceeding it raises ValueError with a distinct message, sized for a 6.4x safety margin on Windows' 1 MB stack.

Does the strata DOM preserve large integers exactly?

No. The C++ DOM stores numbers as double only, so integers above 2^53 lose precision in DOM-based paths like CompiledPath.execute. The Python SAX path via PythonObjectBuilder preserves exact integers at any size.

Which files in the strata C++ core are dead code?

The dead-code map lists count_object_keys, fast_dtoa, arena_allocator, parse_int_fast, collect_newlines_simd, on_uint, and others. These have no callers and must not be built upon; the map is maintained in the architecture documentation.

Why does strata use a FlatMap instead of a hash map for JSON objects?

FlatMap is an insertion-ordered vector of pairs with linear-scan lookup, chosen for cache locality on typical small objects. Its emplace appends without duplicate checks because the parser's duplicate-key policy depends on find returning the first match.