zinsight

AI writes code far faster than anyone documents it. The result is a codebase that works but that no one can hold in their head: endpoints nobody catalogued, integrations nobody listed, a data model that exists only as inference across files. Hand-written architecture docs were always the fix, and they were always stale within weeks. The only version that survives is one the repository generates about itself — which means the analysis has to be static, deterministic and fast enough to run in CI on every merge.

• Split the tool into three clean stages — analyzer, generator, CLI — so what the code discovers stays entirely separate from how it is rendered. New output formats do not touch the analysis, and new language support does not touch the writing.
• Made the analysis purely static. zinsight reads the tree and never executes the project, so it is safe to point at unfamiliar code and produces the same document for the same commit every time. That determinism is what lets the output be committed and diffed.
• Derived structure from evidence rather than convention: endpoints from controllers and route definitions, data models from schema declarations, external contracts from outbound call sites, state from persistence and cache surfaces.
• Wrote to Mermaid so diagrams render natively on GitHub. The architecture picture lives in the repo as text, versions with the code, and shows up in a pull request diff when the shape of the system changes.
• Shipped as both an npm CLI and a GitHub Action from one codebase, so a developer can run it locally and CI can regenerate the doc on merge with no separate integration to maintain.
• Added the sections a reader actually needs before touching code: what the app does, where state lives, what happens on boot, where to look to change something, and an explicit "what this repo isn’t" so nobody hunts for what was never there.

• Published on npm and running as a GitHub Action, at 10,671 lines across a four-module core.
• We use it on our own work: the architecture docs for Zinboard, Zinroute, CaterKart, Sunfinity and Swiggy Celebrations are all zinsight output, regenerated as those systems change.
• Documentation that is a build artefact rather than a chore, so it cannot drift from the code it describes.
• Deterministic and execution-free, which makes it safe to run against a codebase you have just inherited.