DEV Community

Cover image for Directory-as-ID: Scaling Module Discovery Without Configuration
tercel
tercel

Posted on

Directory-as-ID: Scaling Module Discovery Without Configuration

#systemdesign #softwareengineering #architecture #microservices

In the previous volume, we explored the vision of an "AI-Perceivable" world. Now, it’s time to go under the hood. The first technical pillar of the apcore protocol is a deceptively simple idea: Directory-as-ID.

In a traditional microservices or modular architecture, you often have a central registry, a massive YAML configuration file, or a complex dependency injection container. As your system grows from 10 modules to 1,000, this central "phonebook" becomes a bottleneck. It’s the source of merge conflicts, naming collisions, and "Scaling Rot."

apcore solves this by making the file system the source of truth. In this tenth article, we’ll look at the algorithm behind Directory-as-ID and why it’s essential for scaling AI-ready systems.

The Algorithm: From Path to Canonical ID

The principle is straightforward: The relative path of a module file is its unique identity.

If you have a module root directory (e.g., extensions/), apcore scans the files and applies a deterministic mapping:

  1. Remove the Root: extensions/executor/email/send.py -> executor/email/send.py
  2. Remove Extension: executor/email/send.py -> executor/email/send
  3. Normalize Separators: executor/email/send -> executor.email.send (The Canonical ID)

Why this matters for AI:

AI Agents are highly sensitive to names. By using a hierarchical, directory-based naming convention, you naturally create Namespaces. An Agent can quickly differentiate between executor.user.delete and admin.user.delete because the hierarchy provides the context.

Case Study: Zero-Config in apexe

The power of Directory-as-ID is best seen in real-world products like apexe.

apexe: AI-fying the CLI Universe

apexe is a tool that scans existing CLIs (like git or docker) and wraps them into apcore modules. When you run apexe scan git, it generates a hierarchy of modules under your ~/.apexe/modules/ directory.

  • git commit becomes cli.git.commit
  • git push becomes cli.git.push

Because of Directory-as-ID, apexe doesn't need to manage a database of IDs. It simply writes the files to the right folders, and the apcore Registry "perceives" the entire CLI command tree instantly. This enables Dynamic Skill Discovery: if you install a new CLI tool and scan it, your Agent can perceive it immediately without a single server restart.

Technical Rigor: Handling Multi-Language Drift

A core challenge of a language-agnostic standard is that different languages have different naming conventions. Python likes snake_case, while TypeScript prefers camelCase.

The apcore protocol defines strict ID Normalization Rules:

  • Normalization: All IDs are converted to a "Canonical" form (lowercase, snake_case) for the Registry.
  • Language Mapping: Each SDK (Python, TS, Rust) handles the translation between the Canonical ID and the local file name (e.g., SendEmail.ts maps to send_email).

This ensures that even in a polyglot enterprise, the AI Agent sees a single, consistent address space.

Conclusion: Scale is a Design Constraint

Directory-as-ID is more than a convenience; it’s a design constraint for the Agentic Era. It enables Zero-Config Discovery, eliminates registry bottlenecks, and provides a natural namespace for AI perception.

In the next article, we’ll dive into the heart of the engine: The 11-Step Execution Pipeline.

This is Article #10 of the **apcore: Building the AI-Perceivable World* series. Join us as we go deep into the protocol.*

GitHub: aiperceivable/apcore

Top comments (0)