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)
│   ├── rights/              # Music rights metadata
│   ├── scores/              # Game high scores
│   ├── media/               # Multi-provider media search
│   └── (cache is built-in)  # Cache management
├── 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)

Domain Summary

Domain	Transport	Client	Key Methods
mcp	JSON-RPC over HTTPS	MCPClient	search, entities, jukebox, tv, themes
pi	SSH	PIClient	status, logs, restart, backup, deploy
gh	HTTPS	GHClient	workflows, issues, sync, commit
rights	JSON-RPC over HTTPS	RightsClient	search, isrc, iswc, ascap, catalog, export
scores	SSH	ScoresClient	list, get, report, reset
media	HTTPS	MediaClient	search, providers, image
cache	local filesystem	(built-in)	stats, clear

Transport Patterns

• JSON-RPC (mcp, rights): Calls the remote MCP server, which reads/writes data on the Pi
• SSH (pi, scores): Direct SSH to the Pi — faster, no MCP middleman
• HTTPS (gh, media): Direct API calls to GitHub/external providers

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)
• Rights domain (for deploy operations)

Contains:

• GitHubClient — HTTP methods for the GitHub API
• commit_multiple() — atomic multi-file commits via Git Data API
• WORKFLOWS map (name → file)

CLI Dispatch

cli.py routes commands to domain clients:

magmascript <domain> <action> [args...]
    │           │         │
    │           │         └─ action-specific arguments
    │           └─ domain dispatches to Client method
    └─ main() parses args, creates client, calls dispatch

Each domain has a _dispatch_<domain>() function that handles subcommands.

Caching

File-based cache with configurable TTL:

Domain	TTL	Storage
media	24h	~/.cache/magmascript/media/
scores	1h	~/.cache/magmascript/scores/
gh	5min	~/.cache/magmascript/gh/

Cache is transparent — clients check cache before API calls, store results after.