Architecture

How myflames works internally: parser, renderers, advisor, the agent/CI surface, and the teach module.

Design principles

• One analysis, many projections — a plan is parsed and analyzed once, then projected for whoever is asking: flame graph / bar chart / treemap / diagram / tree (for humans), a compact source-grounded digest and JSON sidecar (for AI agents), and an exit code (for CI).
• Zero external dependencies — Python 3.7+ stdlib only. No pip install of MySQL drivers, templating engines, or JS frameworks. The AI-era integrations (MCP transport, exact token counting) live behind optional extras (myflames[mcp], myflames[tokens], myflames[gpt]); the core stays stdlib-only.
• Single parser, multiple renderers — JSON is parsed once into a unified tree. Renderers never re-parse JSON.
• Offline-first output — every HTML file is self-contained. No external scripts, stylesheets, or fonts. Works in Slack DMs, email attachments, and air-gapped environments.
• MySQL + MariaDB parity — the parser auto-detects the engine and normalizes MariaDB's different JSON structure into the same internal tree.
• Source-grounded, never guessing — every advisor rule and optimizer_switch explanation is verified against MySQL/MariaDB server source, so the digest an agent reads is factually correct.

Data flow

Module map

Parser internals

The parser (parser.py) handles two structurally different JSON formats:

• MySQL 8.4+ uses an operation / inputs[] tree structure (format version 2).
• MariaDB 10.11+ uses a query_block / nested_loop / table structure.

MariaDB normalization (_normalize_mariadb*() functions) converts MariaDB's structure into MySQL's operation/inputs tree before parse_node() processes it. This means every renderer and the advisor work with one canonical tree format.

analyze_plan(root) walks the parsed tree and returns a dictionary of detected features: full_scans, hash_joins, temp_tables, filesorts, bnl_nodes, nonsargable_joins, index_suggestions, and more.

Agent & CI surface

The same parsed tree that feeds the SVG renderers also feeds a set of text-and-exit-code projections built for AI agents and pipelines. Raw EXPLAIN ANALYZE FORMAT=JSON is verbose — an LLM spends tokens parsing structure before it can reason — and an SVG is invisible to an agent. These projections give an agent the few facts it needs, source-grounded:

All of this logic is stdlib and unit-tested; only optional transports/counters (myflames[mcp], myflames[tokens], myflames[gpt]) pull in a dependency. See the CLI Reference for flags and exit codes.

Teach module architecture

The teach/ subpackage is a self-contained animation platform:

Every lesson is a single self-contained HTML file (~65-85 KB) with inlined CSS, JS, and SVG. No build step, no bundler, no CI.

Environment advisor rules

advisor.py runs 8 rules that cross-reference the parsed plan with collected server state:

Every suggestion carries a Why: clause grounded in the MySQL cost model. This is enforced by a test.

Testing

The test suite has 1500+ tests across ~19 files in test/, including:

• test_myflames.py — parser, renderers, advisor, HTML wrapper, live-connection mode
• test_sidecar.py / test_compare_sidecar.py — the JSON sidecar + compare delta schemas
• test_digest.py — the token estimator, digest builder, and raw-vs-digest savings comparison (incl. the GPT/tiktoken path)
• test_findings.py — ranked findings + the --fail-on gate evaluator
• test_cli_contract.py — the 0/1/2 exit-code contract and stdout/stderr discipline for every subcommand
• test_mcp_server.py — the MCP tool logic (stdlib, no transport needed)
• test_advisor.py, test_glossary.py, test_nonsargable.py, test_complexity.py, test_teach.py — rule correctness, glossary, and teach cost-model invariants

# Full suite
./run-tests.sh

# Just teach tests
python3 -m unittest discover -s test -p "test_teach.py" -v

Fixtures are generated from live MySQL/MariaDB Docker containers:

./scripts/generate-fixtures.sh           # MySQL fixtures
./scripts/generate-mariadb-fixtures.sh   # MariaDB fixtures