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.

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.

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.

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.

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.

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.

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

<!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>

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.

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

// --- 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 ---

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.

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

// 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

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.

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

// 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

// 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: "[email protected]",

subject: "New contact inquiry",

body: `Contact ID: ${contactId}`

});

}

}

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.

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

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.

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:

1

Frontend (pltf_javascript: ContactPage)

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 />);

2

Route (pltf_route: ContactSubmit)

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;

3

Server Script (pltf_script_server: ContactService)

class ContactService {

async save(data) {

// validate, store, return

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

}

}

4

Page (pltf_page: contact)

<!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>

— End of Document —