Archify
Archify Future and Project: Build a Reproducible Architecture Observatory
A practical Archify roadmap and capstone for versioned topology facts, conformance fixtures, change impact, accessibility, and governed diagram publishing.
What you will learn
- Design a versioned topology package
- Build a conformance fixture and change-impact view
- Plan governed, reversible publishing
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- Versioned topology packages can keep facts, visuals, and decisions together.
- A narrow observatory fixture is more useful than claiming automatic completeness.
- Adopt trace-only, advisory, then enforced publishing with fallback and conformance tests.
The next useful abstraction
Archify's future opportunity is a versioned topology package: typed facts, source revisions, validation receipts, rendered projections, change rationale, and reviewer decisions travel together. A diagram then becomes a living architecture observatory rather than a screenshot that decays after a refactor.
A capability manifest could declare supported diagram types, export formats, interaction modes, source-link policies, and resource budgets. CI could explain why a candidate changed and whether the change is a topology fact, a layout adjustment, or a renderer upgrade.
Capstone: the architecture observatory
Build a service that runs a fixed set of public fixtures through a pinned Archify revision. Store normalized JSON, validation receipts, source-link coverage, visual snapshots, export checksums, accessibility findings, and reviewer approval. Add a change-impact view that highlights which downstream routes or components moved between revisions.
Keep the first version narrow: one repository, one diagram type, and one export. The value is replayability and explainability, not a claim of complete automatic architecture discovery.
Evaluation and governance
Measure edge evidence coverage, false-positive and missing-edge rates, validation stability, render and export latency, artifact size, accessibility, and reviewer time. Add adversarial fixtures for prompt injection in source text, unsafe links, duplicate IDs, stale revisions, and oversized graphs.
Govern publication with signed input revisions, allow-listed source domains, redacted private topology, and a deletion path for sensitive artifacts. A future plugin or host adapter should pass the same conformance suite before it is marked compatible.
A reversible roadmap
Start with trace-only snapshots, then advisory diffs, then enforce publication gates for protected architecture docs. Keep last-good artifacts and a manual editor fallback available. These are proposed directions; the practical contribution is a small fixture, a measurable contract, and evidence that another maintainer can replay.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose one repository, diagram type, export, and public fixture set.
- 2
Store normalized IR, receipts, source coverage, snapshots, checksums, and accessibility.
- 3
Measure evidence, diffs, latency, size, and reviewer time across revisions.
- 4
Roll out trace-only → advisory → enforced gates with signed inputs and fallback.
Copy-ready example
{
"input_revision": "<commit>",
"diagram_type": "architecture",
"ir_sha256": "<hash>",
"source_coverage": 0,
"validation": { "status": "pass" },
"publication": { "status": "review" }
}Frequently asked questions
Is an architecture observatory part of Archify now?
No. It is a proposed project built around the repository's typed IR, validation, source tracing, and exports.
How do I prevent automatic diagrams from becoming stale?
Run pinned fixtures in CI, compare candidate with last-good, require source coverage and review, and keep the input revision beside the artifact.
Sources
- Archify README (captured 2026-08-31)Source checked 2026-08-31
- Archify repositorySource checked 2026-08-31