Architecture

Architecture

Directory Structure

magmascript/
├── core/                    # Framework
│   ├── github.py            # Shared GitHub API client + WORKFLOWS map
│   ├── config.py            # Config loading (env vars + TOML)
│   ├── output.py            # Table/JSON/plain formatters
│   ├── registry.py          # Domain registry
│   └── rpc.py               # JSON-RPC 2.0 client
├── domains/                 # One module per domain
│   ├── mcp/                 # MCP server (JSON-RPC)
│   ├── pi/                  # Raspberry Pi (SSH)
│   └── gh/                  # GitHub (HTTPS)
├── cli.py                   # CLI dispatcher
├── lib/                     # Multi-language wrappers
└── tests/

How Domains Work

Each domain is a Python package that:

1. Registers itself with core/registry.py
2. Provides a Client class with typed methods
3. Returns dataclass instances (not raw strings)

Adding a New Domain

1. Create domains/mydomain/__init__.py:

from magmascript.domains.mydomain.client import MyClient
from magmascript.core.registry import register_domain
register_domain("mydomain", MyClient)

2. Create domains/mydomain/client.py:

class MyClient:
    def __init__(self, config=None):
        cfg = config or get_config()
        # ... setup
    def action(self, args):
        return typed_result

3. Create domains/mydomain/tools.py:

@dataclass
class MyResult:
    field: str

4. Add dispatch to cli.py in the main() function.

5. Register in domains/__init__.py.

Shared Layer: core/github.py

The core/github.py module provides a shared GitHub API client used by:

• gh domain (direct CLI access)
• Future domains that need GitHub operations

Contains the canonical WORKFLOWS map (name → file).