Architecture Overview

System Design Philosophy

The MarlinJai ERP Suite follows these principles:

1. Modular & Composable - Each component is a standalone package that can be used independently
2. Infrastructure Agnostic - Adapter pattern allows swapping databases and file storage providers
3. Type Safe - Full TypeScript across all packages
4. Edge Ready - Designed for Cloudflare Workers and edge deployment

Core Components

0. Brain Core (Shared Infrastructure)

Location: projects/lumitra-infra/brain-core/ | npm: @marlinjai/brain-core (v0.2.0+)

Shared library used by all Brain services. Published on npm — no longer requires file: references. Provides auth middleware, crypto utilities, error handling, and base types.

Exports:

• createAuthMiddleware / createAdminAuthMiddleware — API key authentication
• hashApiKey, generateApiKey, verifyApiKey — key management with timing-safe comparison
• ApiError class and createErrorHandler factory
• Base types: BaseTenant, BaseWorkspace, BaseTenantContext

Brain Core docs

1. Storage Brain (Multi-Tenant File Storage)

Location: projects/lumitra-infra/storage-brain/ (monorepo with API, SDK, and shared types)

Multi-tenant file storage API with workspace isolation, presigned uploads, and quota management.

View full diagram

Key Features:

• Presigned URL uploads and downloads
• Workspace-scoped file isolation
• Tenant quota management
• Multi-provider storage (R2, S3, MinIO via adapter pattern)
• Self-hostable with Docker (PostgreSQL + MinIO)

SDK Usage:

import { StorageBrain } from '@marlinjai/storage-brain-sdk';

const client = new StorageBrain({
  apiKey: 'sk_live_...',
  workspaceId: 'my-workspace',
});
const { fileId, presignedUrl } = await client.requestUpload({
  fileName: 'photo.jpg',
  fileType: 'image/jpeg',
});

Storage Brain docs | SDK docs

2. Data Table (Notion-like Database)

Repository: data-table (monorepo)

A reusable, storage-agnostic Notion-like database component.

View full diagram

Packages:

• @marlinjai/data-table-core - Types, interfaces, adapters
• @marlinjai/data-table-react - React components & hooks
• @marlinjai/data-table-adapter-d1 - Cloudflare D1 adapter
• @marlinjai/data-table-adapter-prisma - Prisma adapter (PostgreSQL, SQLite, etc.)
• @marlinjai/data-table-adapter-memory - In-memory adapter (testing)
• @marlinjai/data-table-file-adapter-storage-brain - Storage Brain integration

Column Types:

• text, number, date, boolean
• select, multi_select
• url, file
• formula, relation, rollup

Data Table docs

3. Email Editor

Repository: email-editor (monorepo)

A visual drag-and-drop email template editor built on MST (MobX State Tree) with MJML export.

View full diagram

Key Architecture Decisions:

• MST for state — fine-grained reactivity, undo/redo via snapshots, type-safe actions
• MJML on export only — no compilation during editing = instant (<16ms) visual feedback
• Framework-agnostic core — core package has zero React dependencies
• Two entry points — client-safe (no MJML) and server-only (with MJML compiler)

Email Editor Architecture | Quickstart guide

4. Framer Clone

Repository: framer-clone

A visual website builder with an infinite canvas, responsive breakpoint system, and Framer-inspired ground wrapper architecture.

View full diagram

Key Architecture Decisions:

• Ground wrappers — each element has independent transform positioning (Framer's approach)
• Zero-render transforms — pan/zoom stored in useRef, updated via direct DOM manipulation
• Subscription pattern — overlays subscribe to transform changes for 60fps synchronization
• MST for state — ProjectStore (domain) + EditorUIStore (UI) split

Framer Clone overview

5. Receipt OCR App

Expense tracking with AI-powered receipt scanning. Uses Google Cloud Vision for OCR, OpenRouter AI for classification, and Data Table for storage. Includes an AI chat sidebar for querying expenses.

View full diagram | Receipt OCR docs

6. Clearify

Documentation site generator. Zero-config by default, with MDX support, Mermaid diagrams, built-in search, and dark mode. This documentation site is built with Clearify.

Clearify docs | Setup guide

Shared Patterns

MobX State Tree (MST)

Both Email Editor and Framer Clone use MST for state management:

• Predictable state with snapshots and patches
• Fine-grained reactivity via MobX observers — only affected components re-render
• Undo/redo via snapshot history
• Type-safe models with runtime validation

Adapter Pattern

Data Table and Storage Brain use the adapter pattern for pluggable backends. This pattern is what enables multi-provider support:

• Data Table: DatabaseAdapter interface (D1, Prisma, Memory adapters)
• Data Table: FileAdapter interface (Storage Brain file adapter)
• Storage Brain: StorageAdapter (R2, S3) and DatabaseAdapter (D1, PostgreSQL)

@marlinjai/ Package Scope

All published packages use the @marlinjai/ npm scope.

Data Flow

View full diagram

Deployment Architecture

Cloudflare (Managed)

View full diagram | Full deployment map

Future Roadmap

1. Real-time Sync — Durable Objects for live collaboration
2. Analytics Dashboard — Business intelligence views
3. Email Editor templates marketplace — Shareable email templates
4. Framer Clone code export — Generate clean React components from designs
5. Framer Clone deployment — Deploy to Cloudflare Pages