> For the complete documentation index, see [llms.txt](https://docs.obto.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.obto.co/applications/platform-architecture.md).

# Platform Architecture

## Platform Architecture

*& Developer Reference*

A complete technical reference for building applications on the OBTO platform. Covers the request lifecycle, collection architecture, component relationships, and full code blueprints for every artifact type.

Version **2.0** • March 2026

For AI Agents & Human Developers

## 1. Platform Overview

OBTO is a distributed, Kubernetes-hosted application platform that stores all application code as database artifacts in MongoDB. There is no traditional filesystem — every component (pages, scripts, routes, stylesheets) lives as a record in a specific collection. The platform uses Vite for frontend module resolution and Express.js for backend routing.

{% hint style="info" %}
Think of OBTO like a CMS for code. You don’t push files to a server — you upsert records into collections. The platform’s runtime reads those records and serves them as if they were files on disk. Understanding this abstraction is the foundation for everything else.
{% endhint %}

## 2. Core Concepts: Domain & Host

Every tool call in OBTO requires two scoping parameters. These are not interchangeable and serve distinct purposes:

| Parameter | What It Is                                                                                  | Example                       | Scope                                                                |
| --------- | ------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------- |
| domain    | The deployment environment. Determines which database and runtime instance serves the app.  | staging, production           | Session-level. Fixed for all tool calls in a given session.          |
| host      | The public hostname that serves pltf\_page, pltf\_javascript, and pltf\_stylesheet records. | myapp.obto.co, app.custom.com | App-level. All page/JS/CSS records for one site share the same host. |
| appName   | The unique identifier for the application. Used to scope all records.                       | my-shop, zsdsd                | App-level. Every tool call requires it.                              |

{% hint style="info" %}
One app (appName) exists in one domain (environment). That app can have one or more hosts. Records that share a host are served together as a cohesive website. A pltf\_page with host=A cannot load a pltf\_javascript with host=B.
{% endhint %}

## 3. Request Lifecycle

Understanding how a request flows through the platform is essential. Here is the complete path from browser to response:

### 3.1 Public Website Request (pltf\_page + pltf\_javascript)

1. Browser requests <https://myapp.obto.co/index>
2. Platform matches the **host** header against pltf\_page records. Finds the page named index with matching host.
3. Platform returns the HTML content from the page record.
4. Browser encounters `<script type="module" src="./App.tsx">` in the HTML.
5. Browser requests `./App.tsx`. Platform resolves this to a pltf\_javascript record named App with the same host.
6. Vite’s transform pipeline processes the module (JSX/TSX → JS), resolves imports (React, etc.), and serves it to the browser.
7. React mounts to the `#root` div. Page is live.

{% hint style="info" %}
OBTO uses `.tsx` as the canonical file extension for all React modules, regardless of whether you write actual TypeScript. This is because Vite’s transform pipeline is configured to process `.tsx` by default. It’s a platform convention, not a language requirement.
{% endhint %}

### 3.2 API Request (pltf\_route + pltf\_script\_server)

1. Client sends a request to an API endpoint (e.g., POST /api/contact).
2. Platform matches the path against pltf\_route records for the app.
3. The route handler executes as an Express.js handler with req and res objects.
4. If the route calls a server script, it uses the **xe.** prefix to dynamically resolve and instantiate the pltf\_script\_server class.
5. The server script executes, returns data, and the route sends the response.

### 3.3 Native App Request (pltf\_script\_client)

Native frontend scripts (pltf\_script\_client) follow a different path. They are not loaded via HTML script tags. Instead, the platform’s native app shell injects them into a pre-configured React runtime environment where all allowed globals are already available on the window object. The script must return a React component as its final statement.

## 4. Component Relationship Map

This is the single most important diagram in this document. It shows how every collection type connects to every other:

```
┌──────────────────── PUBLIC WEBSITE PATH ────────────────────┐

│ │

│ Browser Request │

│ │ │

│ ▼ │

│ pltf_page (HTML) ──── <script src> ───▶ pltf_javascript │

│ │ (React Module) │

│ │ │

│ └──── <link href> ───────▶ pltf_stylesheet │

│ (CSS) │

└────────────────────────────────────────────────────────────┘

┌──────────────────── API / BACKEND PATH ────────────────────┐

│ │

│ Client Request (fetch / form submit) │

│ │ │

│ ▼ │

│ pltf_route (Express) ── xe.prefix ──▶ pltf_script_server │

│ │ (Node.js Class) │

│ │ │ │

│ │ └── xe.prefix ─▶ other servers │

│ ▼ │

│ res.json() / res.send() │

└────────────────────────────────────────────────────────────┘

┌──────────────────── NATIVE APP PATH ──────────────────────┐

│ │

│ Platform App Shell (pre-loaded globals on window) │

│ │ │

│ ▼ │

│ pltf_script_client (React Component) │

│ │ │

│ └── return [ComponentName] ─▶ mounted into shell │

└────────────────────────────────────────────────────────────┘
```

### Binding Rules

* **pltf\_page ↔ pltf\_javascript:** Bound by the `<script src>` tag in the HTML AND by sharing the same host value.
* **pltf\_page ↔ pltf\_stylesheet:** Bound by the `<link href>` tag in the HTML AND by sharing the same host value.
* **pltf\_route ↔ pltf\_script\_server:** Bound by the xe. prefix at runtime. The platform dynamically resolves xe.ClassName to the matching pltf\_script\_server record in the same app.
* **pltf\_script\_server ↔ pltf\_script\_server:** Server scripts can call each other using the same xe. prefix.
* **pltf\_script\_client:** Standalone. No explicit binding needed — injected by the platform’s native app shell.

## 5. Collection Reference

Each collection type has strict rules about what code patterns are allowed. Violating these rules will cause runtime failures.

### 5.1 pltf\_page — HTML Pages

| Property        | Value                                                            |
| --------------- | ---------------------------------------------------------------- |
| Purpose         | HTML layout that serves as the entry point for a public website. |
| Collection Name | pltf\_page                                                       |
| Requires host?  | Yes — must match the hostname serving this site.                 |
| Code Format     | Standard HTML. No framework-specific syntax.                     |

#### Blueprint

```html
<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8" />

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

<title>[App Title]</title>

<!-- Optional: link to pltf_stylesheet -->

<link rel="stylesheet" href="./[StyleName].css" />

</head>

<body>

<div id="root"></div>

<!-- CRITICAL: type="module" is required for Vite resolution -->

<script type="module" src="./[ComponentName].tsx"></script>

</body>

</html>
```

{% hint style="warning" %}
Do NOT mix module scripts with inline global scripts. Do NOT add a second `<script>` block that tries to manually call ReactDOM.render(). The module file handles its own mounting. Choose ONE render path — the module handles it.
{% endhint %}

### 5.2 pltf\_javascript — Public Frontend Modules

| Property        | Value                                                           |
| --------------- | --------------------------------------------------------------- |
| Purpose         | React components and frontend logic for public-facing websites. |
| Collection Name | pltf\_javascript                                                |
| Requires host?  | Yes — must match the page that loads it.                        |
| Code Format     | Standard ESM. Imports ARE allowed.                              |
| Export Pattern  | export default ComponentName;                                   |

#### Blueprint

```javascript
// --- START BLUEPRINT ---

import React from "react";

import { createRoot } from "react-dom/client";

// ... your other standard imports here ...

export default function [ComponentName]() {

return (

// ... your JSX here ...

);

}

// CRITICAL: Mount at the bottom of the file.

const root = createRoot(document.getElementById("root"));

root.render(<[ComponentName] />);

// --- END BLUEPRINT ---
```

{% hint style="warning" %}
NEVER attach the component to the global window object (e.g., window\.App = App). Rely entirely on ES Module exports. Restrict new NPM packages to standard, widely-used libraries.
{% endhint %}

### 5.3 pltf\_script\_client — Native Frontend Components

| Property        | Value                                                                 |
| --------------- | --------------------------------------------------------------------- |
| Purpose         | React components for the native OBTO app shell (not public websites). |
| Collection Name | pltf\_script\_client                                                  |
| Requires host?  | No.                                                                   |
| Code Format     | NO import/export statements. All libraries via window globals.        |
| Final Statement | return \[ComponentName];                                              |

#### Blueprint

```javascript
// NO imports allowed. Destructure from window globals.

const { useState, useEffect } = React;

const { Button, Input, Card } = antd;

function [ComponentName]() {

const [data, setData] = useState(null);

return (

<Card title="My Component">

{/* your JSX */}

</Card>

);

}

// CRITICAL: Must end with return statement.

return [ComponentName];
```

### Available Window Globals (Grouped by Purpose)

| Category               | Globals                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Core React             | React, ReactDOM, createRoot                                                             |
| UI Library             | antd, antdIcons, lucidereact                                                            |
| State Management       | Provider, store, RecoilRoot                                                             |
| Charts & Visualization | Highcharts, HighchartsReact, antdPlots, antv, reactFlow                                 |
| Data & Utilities       | \_, moment, uuidv4, XLSX, format, http, cronstrue                                       |
| Drag & Drop            | Draggable, DraggableCore                                                                |
| Date/Timeline          | Timeline, TimelineMarkers, TodayMarker, CustomMarker, CursorMarker                      |
| Wizards & Steppers     | Stepper, Step, StepWizard                                                               |
| File & Export          | saveAs, print, tus                                                                      |
| Text & Code            | markdownIt, HTMLEncode, hljs, prettierPluginBabel, prettierPluginEstree                 |
| Alerts & Progress      | swal, NProgress                                                                         |
| Other                  | CheckboxTree, ColumnSelect, DailyIframe, dco, fetchEventSource, loadStripe, pageService |

{% hint style="warning" %}
If a requested package is not in the globals list above, STOP. Inform the user that the package is not available in the native environment. Do not hallucinate imports or attempt workarounds.
{% endhint %}

### 5.4 pltf\_route — Express.js Routes

| Property        | Value                                                             |
| --------------- | ----------------------------------------------------------------- |
| Purpose         | Express.js route handlers that serve as API endpoints.            |
| Collection Name | pltf\_route                                                       |
| Requires host?  | No.                                                               |
| Code Format     | CommonJS ONLY. No ES6 export statements.                          |
| Export Pattern  | module.exports.\[RouteName] = \[RouteName];                       |
| Naming Rule     | The exported name MUST exactly match the record’s name attribute. |

#### Blueprint

```javascript
// Route name: ContactSubmit

// The exported name MUST match the record name exactly.

async function ContactSubmit(req, res) {

try {

// Access request data

const { name, email, message } = req.body;

// Call a server script using the xe. prefix

const service = new xe.ContactService();

const result = await service.save({ name, email, message });

res.json({ success: true, id: result.id });

} catch (err) {

res.status(500).json({ error: err.message });

}

}

// CRITICAL: CommonJS named export. Name must match.

module.exports.ContactSubmit = ContactSubmit;
```

### What’s Available in the Route Context

* **req** — Standard Express Request object (req.body, req.params, req.query, req.headers)
* **res** — Standard Express Response object (res.json(), res.send(), res.status())
* **xe.** — Dynamic resolver for pltf\_script\_server classes in the same app

### 5.5 pltf\_script\_server — Backend Logic

| Property          | Value                                                                           |
| ----------------- | ------------------------------------------------------------------------------- |
| Purpose           | Node.js classes containing business logic, data access, and backend processing. |
| Collection Name   | pltf\_script\_server                                                            |
| Requires host?    | No.                                                                             |
| Code Format       | Standard JS classes. NO module.exports.                                         |
| Cross-Referencing | Use xe. prefix to call other server scripts.                                    |

#### Blueprint

```javascript
// Script name: ContactService

// NO module.exports. Just define the class.

class ContactService {

async save(data) {

// Validate input

if (!data.email) throw new Error("Email is required");

// Access the database (platform provides db context)

const record = {

...data,

createdAt: new Date().toISOString(),

status: "new"

};

// Return result to the calling route

return { id: record.id, status: "saved" };

}

async notifyTeam(contactId) {

// Call another server script

const notifier = new xe.NotificationService();

await notifier.sendEmail({

to: "team@shop.com",

subject: "New contact inquiry",

body: `Contact ID: ${contactId}`

});

}

}
```

{% hint style="info" %}
xe. is the platform’s dynamic class resolver. When you write `new xe.ContactService()`, the platform looks up the pltf\_script\_server record named “ContactService” in the current app, loads it, and instantiates the class. This works across both routes and other server scripts. It’s OBTO’s equivalent of require() or import.
{% endhint %}

### 5.6 pltf\_stylesheet — CSS Stylesheets

| Property        | Value                                                         |
| --------------- | ------------------------------------------------------------- |
| Purpose         | Global CSS files loaded by pltf\_page via `<link>` tags.      |
| Collection Name | pltf\_stylesheet                                              |
| Requires host?  | Yes — must match the page that loads it.                      |
| Code Format     | Standard CSS. No preprocessors (no SCSS/LESS).                |
| Loaded Via      | `<link rel="stylesheet" href="./[Name].css" />` in pltf\_page |

## 6. Deployment Quick Reference

All deployment happens through a single tool: `obto_upsert_record`. Here are the required parameters for each collection type:

| Collection           | appName | domain | host         | name                    | script          |
| -------------------- | ------- | ------ | ------------ | ----------------------- | --------------- |
| pltf\_page           | ✓       | ✓      | ✓ Required   | Page name (e.g., index) | HTML content    |
| pltf\_javascript     | ✓       | ✓      | ✓ Required   | Module name (e.g., App) | React/JS code   |
| pltf\_stylesheet     | ✓       | ✓      | ✓ Required   | Style name (e.g., main) | CSS content     |
| pltf\_script\_client | ✓       | ✓      | ✘ Not needed | Component name          | React component |
| pltf\_script\_server | ✓       | ✓      | ✘ Not needed | Class name              | Node.js class   |
| pltf\_route          | ✓       | ✓      | ✘ Not needed | Route/function name     | Express handler |

{% hint style="info" %}
If it’s served to a browser directly (pages, JS modules, CSS), it needs a host. If it runs on the server (routes, server scripts) or is injected by the platform (native client scripts), it doesn’t.
{% endhint %}

## 7. Environment Boundaries

* **ALWAYS pass the current app’s** appName to every tool call. Never hardcode a different app name.
* **NEVER hardcode domain as** `'core'` unless explicitly instructed. The domain is set per session.
* If host is unknown, it MUST be retrieved from app configuration or confirmed with the user before deploying page/JS/CSS records.
* Records with mismatched host values will not be served together. A page at host=A cannot load a script at host=B.

## Appendix: Common Patterns

### A. Full-Stack Example: Contact Form

This example shows how a public website form connects through all layers:

{% stepper %}
{% step %}

### Frontend (pltf\_javascript: ContactPage)

```javascript
import React, { useState } from "react";

import { createRoot } from "react-dom/client";

export default function ContactPage() {

const [form, setForm] = useState({ name: "", email: "" });

const [status, setStatus] = useState(null);

const handleSubmit = async () => {

const res = await fetch("/api/contact", {

method: "POST",

headers: { "Content-Type": "application/json" },

body: JSON.stringify(form)

});

const data = await res.json();

setStatus(data.success ? "sent" : "error");

};

return ( /* JSX form UI */ );

}

const root = createRoot(document.getElementById("root"));

root.render(<ContactPage />);
```

{% endstep %}

{% step %}

### Route (pltf\_route: ContactSubmit)

```javascript
async function ContactSubmit(req, res) {

const svc = new xe.ContactService();

const result = await svc.save(req.body);

res.json({ success: true, id: result.id });

}

module.exports.ContactSubmit = ContactSubmit;
```

{% endstep %}

{% step %}

### Server Script (pltf\_script\_server: ContactService)

```javascript
class ContactService {

async save(data) {

// validate, store, return

return { id: "abc123", status: "saved" };

}

}
```

{% endstep %}

{% step %}

### Page (pltf\_page: contact)

```html
<!DOCTYPE html>

<html lang="en">

<head><meta charset="UTF-8" /><title>Contact</title></head>

<body>

<div id="root"></div>

<script type="module" src="./ContactPage.tsx"></script>

</body>

</html>
```

{% endstep %}
{% endstepper %}

*— End of Document —*