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

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 inside the SUBDIR_MAP dictionary:

# 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 → 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:

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.

MULTI_INSTANCE_TYPES Configuration

The MULTI_INSTANCE_TYPES set defines which types receive automatic sequence numbering:

# 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 (missing the sequence), the validation hook in 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) and routes it to the decisions/ sub-directory per SUBDIR_MAP.

Sequence Generation Backend

The 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 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, 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:

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 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) and looking it up in the SUBDIR_MAP dictionary located in 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), the validation hook in 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). The MULTI_INSTANCE_TYPES set in 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, 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 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.

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