# What Are the @openmaic SDKs? A Deep Dive into OpenMAIC's Modular Architecture

> Explore the @openmaic SDKs: six npm packages for creating, rendering, editing, and managing lesson content in the OpenMAIC platform. Discover their modular architecture and functionalities.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-09-09

---

**The @openmaic SDKs are a family of six specialized npm packages—`@openmaic/dsl`, `@openmaic/renderer`, `@openmaic/editor`, `@openmaic/generation`, `@openmaic/storage`, and `@openmaic/importer`—that together provide the type-safe building blocks for creating, rendering, editing, generating, persisting, and importing lesson content in the OpenMAIC platform.**

Located under `packages/@openmaic/*` in the [THU-MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC) monorepo, these packages follow a strict dependency graph and are published independently to npm as version-0 modules. Each SDK addresses a specific architectural concern, from defining data contracts to converting PowerPoint files into editable slide structures.

## Core SDK Packages Overview

The OpenMAIC platform is composed of six distinct SDKs that form a unified pipeline for lesson content management.

### @openmaic/dsl

The **Data Structure Layer (DSL)** serves as the foundational type system for the entire platform. In `packages/@openmaic/dsl/src/index.ts`, it exports the core `Slide` and `PPTElement` types along with JSON schema definitions (`./schema/*`). This package has zero runtime dependencies, yet all other SDKs depend on it for type-safe contracts.

### @openmaic/renderer

The **Renderer SDK** provides read-only rendering of slide data to the DOM. Found in `packages/@openmaic/renderer/src/elements/SlideCanvas.tsx`, the main `SlideCanvas` component converts DSL slide objects into visual output. It requires React ≥18, react-dom ≥18, motion ≥11, and TailwindCSS ≥4. For correct typography, consuming applications must import the compiled styles: `import '@openmaic/renderer/fonts.css'`.

### @openmaic/editor

Built directly atop the renderer, the **Editor SDK** adds interactive editing capabilities. The primary entry point is `EditableSlideCanvasWithUI` (located in `packages/@openmaic/editor/ui/EditableSlideCanvasWithUI.tsx`), which re-exports the renderer's read-only components and augments them with ProseMirror-based document editing tools and UI chrome.

### @openmaic/generation

The **Generation SDK** handles LLM-driven content creation. Exposed through `packages/@openmaic/generation/src/index.ts`, the `generateSceneContent` function accepts a topic parameter and returns data structures that strictly conform to the DSL types. This package operates without external peer dependencies.

### @openmaic/storage

The **Storage SDK** abstracts persistence across multiple backends. It organizes exports through barrel files for document, asset, and key-value stores, while runtime implementations use sub-paths like `@openmaic/storage/runtime/http` or `@openmaic/storage/runtime/pg`. In `packages/@openmaic/storage/src/browser/BrowserKVStore.ts`, the `BrowserKVStore` class provides an IndexedDB-backed implementation for browser environments. Optional S3 support requires `@aws-sdk/client-s3` as a peer dependency.

### @openmaic/importer

The **Importer SDK** converts external formats into OpenMAIC's native DSL. Defined in `packages/@openmaic/importer/src/importPptx.ts`, the `importPptx` function parses PowerPoint files and returns arrays of `Slide` objects. This enables end-to-end workflows such as `pptx → @openmaic/importer → @openmaic/renderer`.

## Dependency Architecture and Build Order

The @openmaic SDKs follow a strict build dependency chain:

```

@openmaic/dsl → @openmaic/generation → @openmaic/storage → 
@openmaic/importer → @openmaic/renderer → @openmaic/editor

```

When modifying source code, you must rebuild the package (or run `pnpm install` to trigger post-install builds) so downstream packages consume updated `dist/` bundles rather than stale source files. The renderer depends on the DSL definitions, while the editor peer-depends on the entire renderer stack.

## Installation and Versioning Constraints

All @openmaic SDKs are published as **0.x** releases. Under semantic versioning rules for pre-1.0 software, minor version bumps represent breaking changes. Therefore, you must pin **exact versions** in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json):

```json
{
  "dependencies": {
    "@openmaic/renderer": "0.1.0",
    "@openmaic/dsl": "0.1.0"
  }
}

```

Avoid caret (`^`) ranges to prevent accidental breaking changes.

### Monorepo vs. External Consumption

- **Inside the OpenMAIC monorepo**: Use workspace links (`workspace:*`) that point directly to source under `packages/@openmaic/*`.
- **External projects**: Install published npm packages (`npm i @openmaic/renderer`). Your application imports from the compiled `dist/` directory, not the `src/` source files.

## Practical Usage Examples

Below are minimal implementations demonstrating each SDK's public API surface.

### Defining Content with the DSL

```typescript
import type { Slide, PPTElement } from '@openmaic/dsl';

const slide: Slide = {
  id: 'slide-1',
  elements: [
    {
      id: 'elem-1',
      type: 'text',
      content: 'Hello OpenMAIC!',
    } as PPTElement,
  ],
};

```

### Rendering a Slide

```tsx
import { SlideCanvas } from '@openmaic/renderer';
import '@openmaic/renderer/fonts.css'; // Required for fonts and Tailwind v4

function RenderSlide({ slide }: { slide: Slide }) {
  return <SlideCanvas slide={slide} />;
}

```

### Enabling Editing

```tsx
import { EditableSlideCanvasWithUI } from '@openmaic/editor/ui';

function EditSlide({ slide }: { slide: Slide }) {
  return <EditableSlideCanvasWithUI slide={slide} />;
}

```

### Generating Content via LLM

```typescript
import { generateSceneContent } from '@openmaic/generation';

async function generateLesson(topic: string) {
  const content = await generateSceneContent({ topic });
  // Returns DSL-compatible structures
  return content;
}

```

### Persisting Data

```typescript
import { BrowserKVStore } from '@openmaic/storage';

const kv = new BrowserKVStore();
await kv.set('slide-1', slide);
const loaded = await kv.get('slide-1');

```

### Importing External Files

```typescript
import { importPptx } from '@openmaic/importer';

async function loadPptx(file: File) {
  const { slides } = await importPptx(file);
  return slides; // Array of Slide types
}

```

## Key Source Files and Public APIs

Understanding the entry points helps when debugging or extending the platform:

- **`packages/@openmaic/dsl/src/index.ts`**: Declares `Slide`, `PPTElement`, and JSON schemas used across all packages.
- **`packages/@openmaic/renderer/src/elements/SlideCanvas.tsx`**: Implements the read-only canvas component for DOM rendering.
- **`packages/@openmaic/editor/ui/EditableSlideCanvasWithUI.tsx`**: Provides the full editable interface built on ProseMirror.
- **`packages/@openmaic/generation/src/index.ts`**: Exports `generateSceneContent` for AI-driven lesson generation.
- **`packages/@openmaic/storage/src/browser/BrowserKVStore.ts`**: Implements browser-side persistence using IndexedDB.
- **`packages/@openmaic/importer/src/importPptx.ts`**: Contains the PowerPoint parsing logic and `OssUpload` type definitions.

## Summary

- The **@openmaic SDKs** comprise six scoped packages that handle specific concerns: data definitions, rendering, editing, AI generation, storage, and import conversion.
- **Strict dependency ordering** requires building `dsl` before `generation`, `storage`, `importer`, `renderer`, and finally `editor`.
- **Version 0.x** packages require exact version pinning in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) to avoid breaking changes.
- The **renderer requires** importing [`fonts.css`](https://github.com/THU-MAIC/OpenMAIC/blob/main/fonts.css) for correct visual output and depends on React ≥18, motion ≥11, and TailwindCSS ≥4.
- **Storage uses barrel exports** for document stores and sub-path imports for runtime-specific backends like `runtime/http` or `runtime/pg`.

## Frequently Asked Questions

### What is the difference between @openmaic/renderer and @openmaic/editor?

**@openmaic/renderer** provides read-only React components for displaying slide content, while **@openmaic/editor** imports and extends the renderer to add interactive editing capabilities, UI tools, and ProseMirror-based text editing. If you only need to display lessons, use the renderer; if users need to modify content, use the editor.

### Why must I pin exact versions for @openmaic packages?

Because all SDKs are currently at version 0.x (pre-release), semantic versioning treats minor bumps as breaking changes. Using caret ranges (`^0.1.0`) could introduce incompatible type definitions or API changes. Pinning exact versions ensures deterministic builds and prevents runtime mismatches between tightly coupled packages.

### How do I use the storage SDK with PostgreSQL instead of the browser?

Import the PostgreSQL runtime store from the sub-path `@openmaic/storage/runtime/pg` rather than the main barrel export. The `PgRuntimeStore` class (alongside `HttpRuntimeStore`) lives in these sub-paths, while the main export only contains browser-specific and generic storage interfaces.

### Can I use @openmaic/importer without the rest of the OpenMAIC platform?

Yes. The importer converts PPTX or PDF files into standard `Slide` objects defined by `@openmaic/dsl`. You can use `importPptx` to generate DSL-compatible JSON and then process that data with your own rendering pipeline, or pass it directly to `@openmaic/renderer` if you want to display it within the OpenMAIC ecosystem.