How to Capture Custom Brand Marks from a URL in Archify

Archify can extract, normalize, and catalog vector logos from any public URL using a deterministic capture workflow that requires no network access at runtime.

Archify ships with a bounded catalogue of 107 built-in brand marks for instantly recognizable node identities. When your architecture diagram needs a logo that isn't already bundled, the Archify custom brand mark capture from URL workflow lets you fetch the SVG, compute a deterministic digest, and freeze the vector data into the runtime bundle.

The Four-Stage Capture Workflow

Adding a new brand mark to Archify follows a strict separation between network operations and catalogue updates. The CLI fetches and normalizes the asset, but you manually author the entry, ensuring safety and deterministic builds.

Capture the Logo from the URL

Run the capture command to fetch the page, extract the logo vector, and normalize the SVG path using Simple Icons 16.28.0 logic. This is the only step that touches the network.

node archify/bin/archify.mjs brands capture https://example.com --json

The command outputs a JSON object containing the brand identifier, a digest of the source content, the viewBox size, hex color, and normalized SVG path. It intentionally never writes to the catalogue automatically; the operation is read-only and fails closed if the URL is unreachable or the content changes.

Author the Entry in catalog.json

Take the JSON output from the capture step and enrich it with metadata. Open archify/brand-marks/catalog.json and append a new entry with a human-readable title, optional aliases, and applicable domains.

{
  "id": "example",
  "title": "Example Corp",
  "category": "business",
  "aliases": ["ex"],
  "domains": ["example.com"],
  "viewBox": 24,
  "hex": "123456",
  "path": "M10..."
}

The catalogue format is documented in archify/brand-marks/README.md. Each entry is keyed by the brand identifier used later in diagram JSON.

Regenerate the Zero-Runtime Bundle

After editing the catalogue, compile the static asset bundle that the viewer consumes offline. Run the generator script found at archify/scripts/generate-brand-marks.mjs:

npm run generate:brand-marks
npm run check:brand-marks

This produces renderers/shared/generated-brand-marks.mjs, exporting a frozen BRAND_MARKS array. The viewer imports this module directly, guaranteeing that brand marks render without external network requests.

Use the Brand in Diagram Nodes

With the bundle regenerated, use the new brand identifier in your Archify input JSON. The viewer reads the brand field and decorates the node with the SVG logo via the logic in viewer/node-finder.js.

{
  "id": "frontend",
  "type": "service",
  "label": "Web Front-end",
  "brand": "example"
}

If the brand field is omitted, the node falls back to its semantic type color and label. The brand mark is purely visual and does not alter the node's underlying relationships or type classification.

Key Implementation Details

Deterministic Digests: Every capture computes a content hash. If the remote logo changes, the digest mismatch prevents silent catalogue drift, ensuring reproducible builds across environments.

Offline-First Rendering: All vector data lives in generated-brand-marks.mjs. The viewer resolves brand identifiers at runtime by looking up entries in the BRAND_MARKS array, requiring zero external dependencies or API calls.

Explicit Safety: The capture command is unpinned by design. It performs no automatic writes, forcing human review of the extracted vector data before it enters the trusted catalogue in archify/brand-marks/catalog.json.

Summary

• Archify custom brand mark capture from URL workflows normalize remote SVGs into deterministic, version-controlled assets.
• The CLI at archify/bin/archify.mjs extracts logos using Simple Icons 16.28.0 normalization but never auto-commits changes.
• You manually author entries in archify/brand-marks/catalog.json, then regenerate the frozen bundle with npm run generate:brand-marks.
• The viewer consumes pre-bundled vector data from generated-brand-marks.mjs, enabling offline rendering of all 107+ built-in and custom marks.
• Reference brands in diagram JSON via the brand field; the viewer attaches the SVG via data-node-brand attributes in viewer/node-finder.js.

Frequently Asked Questions

How does Archify handle brand marks when the source URL changes?

The capture command computes a deterministic digest of the remote content. If the URL returns different SVG data or becomes unavailable, the digest check fails closed, preventing unverified assets from entering the catalogue. You must explicitly re-run the capture and update the entry in catalog.json to accept the new version.

Can I use the brand mark capture without internet access?

No. The capture step requires network access to fetch the remote page and extract the logo. However, after you run npm run generate:brand-marks, the resulting generated-brand-marks.mjs contains all vector data inline. Subsequent diagram renders work entirely offline because the viewer reads from this frozen bundle rather than fetching URLs.

What happens if I specify a brand that isn't in the catalogue?

If the brand value in your diagram JSON doesn't match any entry in the BRAND_MARKS array, the viewer gracefully falls back to the node's default styling—rendering the type color and label text without an SVG logo. The diagram remains valid; only the visual branding is omitted.

Where is the brand mark data actually stored at runtime?

Runtime brand data lives in renderers/shared/generated-brand-marks.mjs, produced by archify/scripts/generate-brand-marks.mjs. This module exports the BRAND_MARKS constant containing the view box, hex color, and path string for every entry in archify/brand-marks/catalog.json. The viewer imports this module and matches the data-node-brand attribute against the array to retrieve the correct SVG.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}