hermes-web-cli/MODULE_DEVELOPMENT_SPEC_UPDATE.md

Module Development Specification (Updated)

Directory Structure

module-name/
├── module_name/              # Python package (underscore format)
│   ├── __init__.py          # Required for Python package
│   └── init.py              # Exposes variables/functions for web scripts
├── wwwroot/                 # Web resources (auto-routed)
│   ├── *.ui                 # Bricks framework UI files
│   └── *.dspy               # DSPy workflow files  
├── models/                  # Database table definitions (JSON)
├── json/                    # CRUD operation definitions (JSON)
├── init/                    # Initial data (JSON)
├── pyproject.toml           # Package configuration for pip install
└── build.sh                 # Build script (optional)

Key Rules

1. Automatic Routing

• Files in wwwroot/ are automatically accessible via /{module_name}/filename.ext
• No need to register routes manually with ServerEnv
• Supported extensions: .ui, .dspy

2. init.py Purpose

• Primary role: Expose variables and functions for use by other modules and web scripts
• Not for: Route registration, ServerEnv configuration, complex initialization
• Should contain:
  • Module constants and configuration
  • Helper functions callable from .ui/.dspy scripts
  • Variables needed by other Python modules

3. Python Package Naming

• Directory: module-name/ (hyphen format for repository)
• Python package: module_name/ (underscore format for import)
• PyPI package name: module-name (hyphen format)

4. Installation

• Must include pyproject.toml or setup.py
• Must be installable via pip install .
• Should declare dependencies properly

5. Web Script Integration

• .ui and .dspy files can import/use functions from init.py
• Use standard Python import syntax in web scripts
• Keep init.py lightweight and focused on exposure