# How to Capture Custom Brand Marks from a URL in Archify

> Learn how Archify captures custom brand marks from any URL. Extract and catalog vector logos automatically with a unique, network-free workflow.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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.

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/brand-marks/catalog.json) and append a new entry with a human-readable `title`, optional `aliases`, and applicable `domains`.

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/viewer/node-finder.js).

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.