​

Mako Code

Mako Code is an Independent Analytics Environment (IAE) designed for data-driven software engineers, data scientists, and analytics engineers who prefer to work in code rather than through black-box GUIs. It combines a batteries-included FastAPI backend with a highly interactive Svelte + Monaco-Editor front-end to create a seamless local analytics workflow. Unlike conventional BI tools, Mako Code embraces modern developer ergonomics: Polars for blazing-fast dataframe manipulation, Bokeh for interactive visualization, Apache Arrow for zero-copy data interchange, and Pydantic models for type-safe I/O.

The project grew out of the need for a lightweight but opinionated environment that can:

1. Eliminate the boilerplate required to spin up an ad-hoc analytics workspace.
2. Provide a durable path from exploration → production without changing tools or file formats.
3. Offer best-in-class editor UX (Monaco) inside a modern reactive UI (SvelteKit).
4. Stay fully open-source and free of proprietary lock-in or cloud dependencies.

​

Why Another Analytics Tool?

Most data-centric teams end up juggling multiple tools: Jupyter notebooks for quick prototypes, SQL IDEs for data warehouse work, and BI dashboards for visualization. Every context switch introduces friction, and moving code from one environment to another is tedious.

Mako Code unifies these workflows:

• One Code Editor – Monaco handles Python, SQL, JSON, YAML, and more.
• One DataFrame Library – Polars is the default (no Pandas). It is multi-threaded and Arrow-native.
• One Visualization Layer – Bokeh ships in the base image; you can plug in Altair or Seaborn if desired.
• One Deployment Target – Everything runs as a local FastAPI service. Deploy the same container to staging or production.

​

Feature Checklist

​

Demo Walk-through

The following animated sequence outlines the typical workflow:

1. Import Data – Press ⌘⇧I, drop one or more Parquet files. The backend stores them in data/datasets/, extracts column types via Polars, and caches the schema in context.json.
2. Explore – Choose Analyze in the right sidebar. Mako Code creates a new editor tab pre-populated with starter Polars code:

import polars as pl
from functions import *  # your saved helpers

# Load dataset lazily
lf = pl.scan_parquet("data/datasets/iceberg_orders.parquet")

(
    lf
    .group_by("customer_id")
    .agg(pl.col("total_price").sum())
    .sort("total_price", descending=True)
)

3. Visualize – Add a Bokeh plot at the bottom of your script:

from bokeh.plotting import figure, show
p = figure(height=300, x_axis_label="Customer", y_axis_label="Revenue")
p.vbar(x=top["customer_id"], top=top["total_price"], width=0.9)
show(p)

4. Save Snapshot – Press ⌘S to commit the current buffer into data/versions/<tab>/YYYY-MM-DDThh-mm-ss.py. The sidebar’s Version History panel is updated automatically.

​

Under the Hood: High-Level View

flowchart LR
    subgraph Front-End (SvelteKit)
        A[MonacoEditor.svelte] -->|POST /api/execute| B(Backend)
        A -- Drag & Drop --> C[DataImportModal.svelte]
        C -- Upload --> B
        Sidebar[RightSidebar.svelte] -- GET /api/dataset/* --> B
        VersionHistory.svelte -- GET /api/version/* --> B
    end
    subgraph Back-End (FastAPI)
        B(main.py)
        B -->|Polars| D[functions/ingestion.py]
        B -->|SQL Parsing| E[functions/sql_parser.py]
        B -->|User Functions| F[functions/utils.py]
    end

The split-pane editor lives entirely in the browser; only evaluation requests, dataset uploads, and version metadata touch the FastAPI server. Because FastAPI is stateless and file-based, the entire workspace can be persisted merely by archiving the data/ directory.

​

Next Steps

• Read the Installation Guide to get Mako Code running locally or inside Docker. • Dive into Project Architecture for an in-depth look at backend modules and frontend component trees. • Browse the API Reference for an exhaustive list of REST endpoints. • Contribute code via GitHub after reviewing the Contributing Guide.