Skip to content

docs: add public proofs and scenario recipes for the five promoted 3.1 diagram types #916

Closed

Description

@tt-a1i

Problem and value

Archify 3.1.0 promotes ERD, Class, Tree, Timeline and Waterfall, but the public gallery/recipe inventory still principally demonstrates the legacy modes plus ERD. The package already contains examples for the new renderers; visitors need checked, explorable examples that explain when to choose them. Release preparation (#914, #915) made the supported inventory explicit without inventing missing gallery proofs.

Scope

Reuse the shipped example sources where they tell a clear story. Add a bounded scenario and public proof for Class, Tree, Timeline and Waterfall; assess the existing ERD/database-schema proof and reuse it rather than duplicating it. Keep canonical scenario data in archify/recipes/scenarios.mjs and feed existing gallery generation/presentation machinery. This is showcase/authoring work, not a renderer feature or redesign.

Useful candidate stories: interfaces and implementations (Class), repository/module hierarchy (Tree), a documented change history (Timeline), and request phase timings (Waterfall). Final scenarios should answer one concrete question each.

Acceptance

  • Each of the five promoted types has an identifiable public example, editable typed JSON, explorable HTML, a concise question, and a copyable starter prompt.
  • Every new recipe has equivalent English/Chinese copy, evidence requirements and when-not-to-use guidance. Existing ERD proof remains reusable.
  • Validate/deliver/provenance/browser gates pass using the implementation revision. Separate automated receipts from human screenshot review.
  • Inspect matched light/dark captures at 1440×900 and a narrow reader viewport; inspect routing, text and controls rather than treating a green receipt as visual acceptance.
  • Timeline dates cite a source when factual. Waterfall durations cite measurements when measured; synthetic values are explicitly labelled illustrative. Conceptual ERD models are distinguished from physical schemas.
  • Use public/redacted fixture material. No local project paths, private repository content or unsupported performance claims enter public artifacts.
  • Generated manifest, links, example HTML and applicable canonical archive checks remain fresh. Record source revision and regeneration commands.

Follow-up

This supplies the verified assets/recipe IDs consumed by the README (#917) and website (#918) expansion tasks. Integrate through dev; follow the normal stable promotion process rather than changing the immutable 3.1.0 tag.

Activity

  1. hemv-857 commented on Oct 17, 2026

    @hemv-857

    Taking this one — scope comment per CONTRIBUTING.

    Plan (staying inside the issue's acceptance):

    • Add one public proof each for Class, Tree, Timeline and Waterfall, reusing shipped example sources (the payments suite: payments.class.json, payment-platform.tree.json, payment-incident.timeline.json, checkout-request.waterfall.json — a coherent story next to the existing orders.erd proof). All four already render 9/9 checks at the showcase profile with zero composition debt on current dev.
    • Register them as CASES in website/src/data/gallery-presentation.mjs, extend SHAPES in scripts/build-gallery.mjs, and add matching SCENARIO_RECIPES entries in archify/recipes/scenarios.mjs with equivalent English/Chinese copy, evidence requirements and when-not-to-use guidance.
    • Rebuild the checked-in docs/ gallery outputs and update the gallery/start/guide test expectations for the new inventory.
    • Reuse the existing ERD proof unchanged (no duplicate database-schema proof).

    Working in a branch off dev; will open as draft for scope visibility before review.

  2. tt-a1i commented on Oct 25, 2026

    @tt-a1i
    OwnerAuthor

    Completed on dev through #986, integrated by #1102 at commit 10b4dd5. Original contribution history is retained.

    The bounded promoted-type recipe/proof slice is implemented: Class, Tree, Timeline and Waterfall reuse shipped inputs alongside the existing ERD proof, with bilingual guidance and Start/Guide/gallery integration. This is completion on dev; stable promotion/site deployment remain separate.

    The exact integrated candidate 98efbfc passed CI run 40177166414: 19 successful jobs, no failures, two deployment-only skips. Closing as completed in the development branch; this does not announce a release or a live installation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions