Diagrams as Code: How to Keep Architecture Docs in Sync with Your Codebase

·4 views

Outdated architecture diagrams stored as PNG or draw.io files are a common pain point for engineering teams, as they cannot be diffed, reviewed, or reliably updated alongside code changes. The 'diagrams as code' approach treats diagrams as plain text files, making them trackable via Git, reviewable in pull requests, and verifiable by CI pipelines. Tools like Mermaid, PlantUML, D2, and Structurizr DSL offer varying strengths, with Mermaid being a low-friction default since GitHub and GitLab render it natively. A practical workflow involves requiring any architecture-changing PR to include a corresponding diagram update, enforced through PR templates and automated syntax validation via mermaid-cli. Architecture data already present in repos — such as docker-compose or Terraform files — can also be parsed programmatically to auto-generate diagrams, reducing the risk of them becoming stale.

Read the full story at DEV Community

This is an AI-generated summary. ShortSingh links to the original source for the complete article.

Discussion (0)

Insufficient source content to report accurately

The provided source contains no readable article body — only a title and a restricted URL. There are no verifiable facts about who was involved, what exactly occurred, when or where it happened, or why. Reporting on this item would require inventing details not present in the source. No summary can be responsibly produced from this content.

0 comments Read more at Hacker News

ProgrammingDEV Community ·

Dev Builds Theatre Prop Continuity Tracker to Catch Staging Errors

A developer created Prop Continuity Desk, a rehearsal planning web app designed to help small theatre productions track the physical movement of props across scenes. The app is built around a fictional six-scene play with twelve props and detects two key mistakes: placing the same prop in two locations within one scene, and moving a prop between scenes without a recorded transfer cue. It uses Next.js, React, TypeScript, and Sanity as its content backend, with scene reviews stored in separate documents to avoid overwriting the data being reviewed. A practice-copy feature lets visitors explore the rules without altering the live production plan, and any exported cue sheet from a practice session is clearly labelled as such. The project was built using Codex starting 26 September 2026, with the AI proposing the scenario, writing the code, and running the tests under the account owner's authorization.

0 comments Read more at DEV Community

ProgrammingDEV Community ·

Sekura JS Explores Sharing Software Verification Proofs Without Exposing Source Code

Sekura JS is developing an approach that separates a software module's source code from its verification contract (SJV) and proof artifact (SJP), allowing developers to share evidence of formal verification without disclosing proprietary implementations. The SJV document specifies the properties a module claims to satisfy, while the SJP carries the mathematical evidence produced during verification. A third-party verifier can replay the stored SMT obligations using tools like Z3 or CVC5 to confirm their validity without ever seeing the underlying source code. However, the project acknowledges a key limitation: replaying an SJP can confirm that the mathematical proofs are valid, but cannot independently verify that those proofs were actually generated from the specific private codebase the developer claims. This creates an explicit trust boundary between the private source code and the proof artifacts exchanged between parties.

0 comments Read more at DEV Community

ProgrammingDEV Community ·

Where Game Development Budgets Actually Go, Explained by Category

Game development costs are typically split across five core categories: engineering, art and audio, design, QA and testing, and project management. Engineering tends to consume the largest share, usually between 40 and 50 percent, covering gameplay systems, networking, platform work, and performance optimisation. Art and audio follow at 20 to 30 percent, while design, QA, and project management each account for roughly 5 to 15 percent. These ranges are based on agency-scoped projects and shift depending on genre, platform targets, team structure, and scope. When budgets are limited, understanding which category drives the most complexity for a given project can help teams prioritise spending more effectively.

0 comments Read more at DEV Community