Your first module

modules/my_module/
├── manifest.yaml           # required – identity, requirements, dependencies, frontend
├── module.py               # required – one Module subclass, instantiated once per process
├── events.py               # recommended – Pydantic payload shapes you emit
├── tests/                  # pytest
├── panel/index.tsx         # the module page entry
├── widgets/*.tsx           # dashboard cards
├── uv.lock                 # commit it – pins your Python dependencies
├── .venv/ · .dist/ · node_modules/   # created by the platform, gitignored
└── README.md               # rendered on the module detail page

from mate.sdk import Module, ModuleContext, job, on_event, route


class MyModule(Module):
    id = "my_module"  # must equal manifest.id

    async def _compute(self, ctx: ModuleContext) -> dict:
        async with ctx.event_log as log:
            rows = await log.duckdb_fetch(
                "SELECT activity, count(*) AS events FROM events GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
            )
        return {"top_activities": [{"activity": a, "events": n} for a, n in rows]}

    @route.get("/top-activities")
    async def top_activities(self, ctx: ModuleContext) -> dict:
        cached = await ctx.cache.get("top_activities")
        if cached is not None:
            return cached
        result = await self._compute(ctx)
        await ctx.cache.set("top_activities", result)
        return result

    @on_event("log.imported")
    @job(progress=True, title="My Module - precompute")
    async def precompute(self, ctx: ModuleContext, payload: dict) -> None:
        await ctx.progress.update(0.1, "Loading log")
        await ctx.cache.set("top_activities", await self._compute(ctx))
        await ctx.progress.update(1.0, "Done")

id: my_module
name: My Module
version: 0.1.0
category: attribute
description: Lists the most frequent activities in the log.
license: MIT

requirements:
  event_log:
    log_model: case_centric
    required_columns: [case_id, activity, timestamp]
    min_events: 1

provides: [my_module.top_activities]
consumes: [log.imported]

dependencies:
  python:
    requires-python: ">=3.12"
    inherit: [pandas]