Add architecture documentation

[koxudaxi]

Summary by CodeRabbit

• Documentation
  • Expanded the Architecture guide with a generated “architecture inventory” covering parser routes, inheritance, configuration surface, formatter options, and output backends.
  • Added “Architecture” to the documentation navigation and README links.
• Chores
  • Improved automated architecture docs synchronization so updates to the inventory are detected and regenerated in CI.
• Tests
  • Added automated checks and expected-output validation for the architecture inventory generator to ensure the docs staleness check passes.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new scripts/build_architecture_docs.py script that uses AST inspection and runtime introspection to generate and inject a Mermaid diagram plus four markdown tables into docs/architecture.md. The doc also gains a static narrative section. Tests, tox, the GitHub sync workflow, and the MkDocs nav are updated accordingly.

Changes

Architecture Documentation Auto-Generation

Layer / File(s)	Summary
Script: constants, AST helpers, and source analysis scripts/build_architecture_docs.py	Establishes path setup, module-level constants (BEGIN_MARKER, END_MARKER, PARSER_ROUTE_OVERRIDES, PARSER_CONFIG_CLASSES), AST helper functions for identifier extraction and match-pattern analysis, parser_routes_from_source() (reads _build_parser() via AST to map InputFileType → parser route), and parser_inheritance_edges() (scans parser/*.py for class hierarchies).
Script: table/diagram generators, file updater, and CLI scripts/build_architecture_docs.py	Implements generate_parser_diagram(), generate_input_routes_table(), generate_output_backend_table(), generate_config_table(), generate_formatter_table(), generate_architecture_inventory(), update_docs_file(check=...) (regex-replaces marker-delimited block with drift detection), and the argparse-based main() CLI with --check mode.
Architecture doc: static narrative and auto-generated inventory docs/architecture.md	New 291-line document with static sections (generation pipeline diagram, CLI vs generate() API responsibilities, parser model, intermediate model graph, output backends, rendering/formatting, metadata output, dynamic model generation, performance notes) and the auto-generated inventory block (parser inheritance diagram, input routes table, output backends table, config surface table, formatter names table) plus synchronization instructions.
Tests, CI wiring, tox, and navigation tests/test_build_architecture_docs_script.py, tox.ini, .github/workflows/generated-docs-sync.yaml, zensical.toml, README.md	Adds subprocess-based --check exit-code test and direct generate_architecture_inventory() content assertion. Adds python scripts/build_architecture_docs.py to the tox generated-docs env. Adds the script and docs/architecture.md to the workflow trigger paths and patch-detection array. Registers "Architecture" = "architecture.md" in the MkDocs nav and adds Architecture link to README.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• koxudaxi/datamodel-code-generator#3095: The main PR's updates to .github/workflows/generated-docs-sync.yaml (adding scripts/build_architecture_docs.py and docs/architecture.md to the generated-docs sync triggers/patch logic) directly extend the workflow owned by that PR.
• koxudaxi/datamodel-code-generator#3130: Both PRs modify .github/workflows/generated-docs-sync.yaml's trigger logic—Add manual generated docs sync trigger #3130 adds workflow_dispatch, while the main PR expands the push path triggers and patch comparison to include the new architecture-docs generator inputs.
• koxudaxi/datamodel-code-generator#3135: Both PRs extend the generated-docs CI/Tox pipeline (updating tox.ini and .github/workflows/generated-docs-sync.yaml) to run documentation generation scripts as part of the release-time doc sync flow.

Poem

🐇 A new page appeared in the docs today,
With parsers and routes in a Mermaid display.
A script digs through AST trees with care,
And keeps every table refreshed and fair.
If the inventory drifts, CI will say "Nay!" 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add architecture documentation' accurately and concisely describes the main changeset, which adds comprehensive architecture documentation including a new docs/architecture.md file, supporting script, workflow updates, and configuration changes.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/architecture-overview

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📚 Docs Preview: https://pr-3464.datamodel-code-generator.pages.dev

[codspeed-hq]

Merging this PR will improve performance by 15.63%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 11 improved benchmarks
⏩ 98 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	WallTime	test_perf_large_models_pydantic_v2	3.7 s	3.1 s	+17.31%
⚡	WallTime	test_perf_complex_refs	2 s	1.7 s	+17.01%
⚡	WallTime	test_perf_multiple_files_input	3.6 s	3.1 s	+16.09%
⚡	WallTime	test_perf_deep_nested	5.2 s	4.5 s	+15.98%
⚡	WallTime	test_perf_duplicate_names	1,084.1 ms	936.4 ms	+15.77%
⚡	WallTime	test_perf_aws_style_openapi_pydantic_v2	1.9 s	1.7 s	+15.61%
⚡	WallTime	test_perf_openapi_large	2.9 s	2.5 s	+15.24%
⚡	WallTime	test_perf_graphql_style_pydantic_v2	806.7 ms	700.6 ms	+15.14%
⚡	WallTime	test_perf_all_options_enabled	5.4 s	4.7 s	+15.1%
⚡	WallTime	test_perf_stripe_style_pydantic_v2	2 s	1.8 s	+14.43%
⚡	WallTime	test_perf_kubernetes_style_pydantic_v2	2.6 s	2.3 s	+14.24%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing docs/architecture-overview (ba5159e) with main (8abb86c)²}

Footnotes

1. 98 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (3dd90d7) during the generation of this report, so 8abb86c was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8abb86c) to head (ba5159e).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #3464   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          148       149    +1     
  Lines        32156     32176   +20     
  Branches      3767      3767           
=========================================
+ Hits         32156     32176   +20     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Breaking Change Analysis

Result: No breaking changes detected

Reasoning: PR #3464 is purely additive documentation/tooling. It adds a new docs/architecture.md page, a new scripts/build_architecture_docs.py helper that generates an inventory section from source, an accompanying test and expected-output fixtures, and registers the new page/script in zensical.toml nav, the generated-docs-sync workflow, tox.ini, README.md, and the llms.txt/llms-full.txt docs. The deleted-lines.txt file is empty, confirming no lines were removed. Nothing changes generated code output, Jinja2 templates, CLI options, the Python API, default values/behavior, supported Python versions, or error handling. Therefore there are no breaking changes for end users.

---

This analysis was performed by Claude Code Action

[github-actions]

🎉 Released in 0.65.0

This PR is now available in the latest release. See the release notes for details.