# Routing Solutions in Arc-Kit: 4 Methods for Organizing Architecture Artifacts

> Explore Arc-Kit's 4 routing solutions file-system mapping multi-instance document types command decision trees and GitHub Pages hash-based URLs to organize architecture artifacts.

- Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Arc-Kit uses four layered routing solutions—file-system subdirectory mapping, multi-instance document types, command decision trees, and GitHub-Pages hash-based URL routing—to keep architecture artifacts organized and accessible.**

The `tractorjuice/arc-kit` repository implements a deterministic routing architecture that couples document semantics with physical layout and navigation. Understanding these routing solutions in arc-kit is essential for extending the framework or troubleshooting why files land in specific directories.

## File-System Subdirectory Routing

Arc-Kit enforces a strict **file-system subdirectory routing** scheme that maps every artifact to a specific folder based on its ARC document type code. This prevents orphaned files and guarantees a consistent project structure across all Arc-Kit implementations.

### The SUBDIR_MAP Dictionary

The routing logic lives in [`arckit-gemini/hooks/scripts/hook_utils.py`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-gemini/hooks/scripts/hook_utils.py) inside the `SUBDIR_MAP` dictionary:

```python

# arckit-gemini/hooks/scripts/hook_utils.py

SUBDIR_MAP = {
    "ADR":  "decisions",
    "DIAG": "diagrams",
    "DFD":  "diagrams",
    "WARD": "wardley-maps",
    "DMC":  "data-contracts",
    "RSCH": "research",
    "AWRS": "research",
    "AZRS": "research",
    "GCRS": "research",
    "DSCT": "research",
}

```

When a new file is created, validation hooks extract the document type from the filename (e.g., [`ARC-001-ADR-001-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-001-ADR-001-v1.0.md) → `ADR`) and verify the file resides in the mapped subdirectory. If the file is outside the required folder, the hook rejects the operation.

### Deriving Target Paths Programmatically

You can replicate the routing logic in custom scripts using the same mapping:

```python
import os
from pathlib import Path
from arckit_gemini.hooks.scripts.hook_utils import SUBDIR_MAP

def target_path(project_root: Path, arc_filename: str) -> Path:
    """
    Build the full filesystem path where an ARC file should be stored.
    """
    # Extract the type code: ARC-001-<TYPE>-v1.0.md → <TYPE>

    doc_type = arc_filename.split("-")[2]               # naive extraction for demo

    subdir = SUBDIR_MAP.get(doc_type, "")
    if not subdir:
        raise ValueError(f"Unsupported document type: {doc_type}")

    return project_root / "projects" / subdir / arc_filename

# Example usage

proj_root = Path("/repo")
print(target_path(proj_root, "ARC-001-ADR-001-v1.0.md"))

# → /repo/projects/decisions/ARC-001-ADR-001-v1.0.md

```

## Multi-Instance Document Type Routing

Some artifact types support **multi-instance document routing**, allowing projects to contain multiple sequentially numbered documents of the same type (e.g., `ADR-001`, `ADR-002`). Arc-Kit enforces this through sequence numbers and dedicated sets in [`hook_utils.py`](https://github.com/tractorjuice/arc-kit/blob/main/hook_utils.py).

### MULTI_INSTANCE_TYPES Configuration

The `MULTI_INSTANCE_TYPES` set defines which types receive automatic sequence numbering:

```python

# arckit-gemini/hooks/scripts/hook_utils.py

MULTI_INSTANCE_TYPES = {
    "ADR", "DIAG", "DFD", "WARD", "DMC",
    "RSCH", "AWRS", "AZRS", "GCRS", "DSCT",
}

```

When a user attempts to create a document like [`ARC-001-ADR-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-001-ADR-v1.0.md) (missing the sequence), the validation hook in [`arckit-gemini/hooks/scripts/validate-filename.py`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-gemini/hooks/scripts/validate-filename.py) automatically rewrites the filename to include the next available sequence number (e.g., [`ARC-001-ADR-003-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-001-ADR-003-v1.0.md)) and routes it to the `decisions/` sub-directory per `SUBDIR_MAP`.

### Sequence Generation Backend

The [`scripts/python/generate-document-id.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/python/generate-document-id.py) helper computes the next sequence number by scanning the target subdirectory, ensuring the file-system routing stays synchronized with the logical document identity.

## Command Decision-Tree Routing

Arc-Kit provides **command decision-tree routing** through the `/arckit.start` onboarding command. This visual workflow guides users to the appropriate next command based on their current project stage and existing artifacts.

The decision tree is dynamically generated from the same `SUBDIR_MAP` and `MULTI_INSTANCE_TYPES` metadata used for file-system routing, ensuring the CLI interface remains consistent with the physical directory structure. According to the [`docs/guides/start.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/start.md) file, the tree is organized by workflow area and presents choices such as initializing a new project, generating a specific document type, or building the documentation site.

Extending the decision tree requires only adding entries to `SUBDIR_MAP`; the CLI automatically surfaces new document types in the routing interface without manual UI updates.

## GitHub-Pages Hash-Based URL Routing

The `/arckit.pages` command generates a static documentation site that uses **GitHub-Pages hash-based URL routing** to create shareable, deep-linkable pages. This client-side routing scheme enables instant navigation without server-side configuration.

As documented in [`docs/guides/pages.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/pages.md), the URL structure follows this pattern:

```

https://org.github.io/repo/#projects/001-my-app/ARC-001-REQ-v1.0.md

```

The hash fragment (`#projects/...`) maps directly to a file path in the repository. Client-side JavaScript parses the hash, resolves it to the corresponding Markdown file, and renders the content—including Mermaid diagrams—without page reloads. This zero-backend approach ensures deterministic routing that mirrors the file-system structure established by `SUBDIR_MAP`.

### Constructing Deep Links

You can generate these URLs programmatically:

```python
def arc_hash_url(base_url: str, project_id: str, filename: str) -> str:
    """
    Build a hash-based URL for a given ARC artifact.
    """
    return f"{base_url}/#{project_id}/{filename}"

# Example

print(arc_hash_url(
    "https://myorg.github.io/arc-repo",
    "projects/001-payment-service",
    "ARC-001-REQ-v1.0.md"
))

# → https://myorg.github.io/arc-repo/#projects/001-payment-service/ARC-001-REQ-v1.0.md

```

## Summary

- **File-system subdirectory routing** uses the `SUBDIR_MAP` dictionary in [`hook_utils.py`](https://github.com/tractorjuice/arc-kit/blob/main/hook_utils.py) to enforce that every ARC document type lives in a specific folder (e.g., `ADR` → `decisions/`).
- **Multi-instance document type routing** leverages the `MULTI_INSTANCE_TYPES` set to automatically append sequence numbers (e.g., `ADR-001`) and validate placement, ensuring scalable organization of repeated artifact types.
- **Command decision-tree routing** provides a visual CLI workflow in `/arckit.start` that dynamically guides users to the correct command based on current project state and the same routing metadata.
- **GitHub-Pages hash-based URL routing** generates static sites with deep-linkable URLs using hash fragments (e.g., `#projects/...`) that map directly to file paths, enabling client-side navigation without server configuration.

## Frequently Asked Questions

### How does Arc-Kit determine which folder a new document should be placed in?

Arc-Kit determines the target folder by extracting the document type code from the ARC filename (e.g., `ADR` from [`ARC-001-ADR-001-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-001-ADR-001-v1.0.md)) and looking it up in the `SUBDIR_MAP` dictionary located in [`arckit-gemini/hooks/scripts/hook_utils.py`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-gemini/hooks/scripts/hook_utils.py). If the file is not in the mapped subdirectory, validation hooks reject the creation. This ensures that decision records always land in `decisions/`, diagrams in `diagrams/`, and research documents in `research/`.

### What happens if I try to create a document type that supports multiple instances without a sequence number?

If you attempt to create a multi-instance document type—such as an ADR or DIAG—without a sequence number (e.g., [`ARC-001-ADR-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-001-ADR-v1.0.md)), the validation hook in [`arckit-gemini/hooks/scripts/validate-filename.py`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-gemini/hooks/scripts/validate-filename.py) automatically rewrites the filename to include the next available sequence number (e.g., [`ARC-001-ADR-003-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-001-ADR-003-v1.0.md)). The `MULTI_INSTANCE_TYPES` set in [`hook_utils.py`](https://github.com/tractorjuice/arc-kit/blob/main/hook_utils.py) defines which types receive this treatment, ensuring every instance is uniquely identifiable and correctly routed to its designated subdirectory.

### How does the GitHub-Pages URL routing work without a server-side backend?

The static site generated by `/arckit.pages` uses client-side JavaScript to parse the URL hash fragment (e.g., `#projects/001-my-app/ARC-001-REQ-v1.0.md`) and load the corresponding Markdown file from the repository. As documented in [`docs/guides/pages.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/pages.md), this hash-based routing scheme maps directly to the file-system structure established by `SUBDIR_MAP`, enabling deep linking and instant navigation without requiring server-side routing configuration or backend infrastructure.

### Can I add a custom document type to Arc-Kit's routing system?

Yes, extending the routing system requires only adding the new document type code to the `SUBDIR_MAP` dictionary in [`arckit-gemini/hooks/scripts/hook_utils.py`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-gemini/hooks/scripts/hook_utils.py) and, if the type supports multiple instances per project, including it in the `MULTI_INSTANCE_TYPES` set. Once added, the validation hooks, the `/arckit.start` command decision tree, and the GitHub-Pages URL routing will automatically recognize and support the new type without additional configuration.