@ossy/platform

Express-based application server runtime for the Ossy platform. It reads the build manifest produced by @ossy/app build and wires up pages, API routes, tasks, actions, integrations, aggregates, and startup hooks — all without any server-side configuration.

What it does

At startup @ossy/platform:

1. Loads build/manifest.json produced by @ossy/app build.
2. Registers and runs all startup hooks (*.startup.js) in order.
3. Connects all integrations (*.integration.js) by calling connect({ env }).
4. Registers all tasks (*.task.js) with TaskService and starts the cron scheduler.
5. Registers all resource templates (*.resource.js) with registerResourceTemplate.
6. Rebuilds all aggregates (*.aggregate.js) from the event store.
7. Registers all actions (*.action.js) with ActionService.
8. Starts an Express server that routes requests to pages (*.page.jsx) and API handlers (*.api.js).
9. Auto-mounts every action at POST /actions ({ action, payload }).

Quick start

# In your app directory
npm install @ossy/app @ossy/platform

# Build the app
npx app build

# Start the server
npx platform start

Or programmatically:

import { startServer } from '@ossy/platform'

const { port, close } = await startServer({
  cwd: process.cwd(),   // defaults to process.cwd()
  buildDir: 'build',    // defaults to 'build'
  port: 3000,           // also reads --port / PORT env var
})

Server configuration

The server reads configuration from:

• --port / -p CLI flag, or the PORT environment variable (default 3000).
• build/manifest.json — produced by @ossy/app build.
• process.env — used by integrations for their credentials and by startup hooks.

Optional environment variables used by the platform itself:

| Variable | Description | |---|---| | DB_URL | MongoDB connection string. Required for tasks and aggregates. | | API_URL + OSSY_API_KEY | SDK configuration. When set, tasks receive a pre-configured SDK instance. | | PORT | HTTP port. |

Exported API

import {
  startServer,
  loadManifest,
  resolveEntryUrl,
  ConfigService,
  ActionService,
  StorageClient,
  S3Client,
  LocalStorageClient,
  getSystemResourceTemplates,
  normalizeAndValidateDocumentContent,
  validateResourceTemplatesForImport,
} from '@ossy/platform'

ActionService

Registry for *.action.js command handlers.

import { ActionService } from '@ossy/platform'

// Invoke an action from server-side code (bypasses HTTP)
const result = await ActionService.invoke('orders/create', {
  payload: { ... },
  req: { userId: 'user-123', workspaceId: 'ws-456' },
})

// Look up a registered action
const action = ActionService.get('orders/create')  // { id, access, run } | null

// List all registered actions
const all = ActionService.all()

getSystemResourceTemplates

Returns all resource templates registered from *.resource.js files.

import { getSystemResourceTemplates } from '@ossy/platform'

const templates = getSystemResourceTemplates()
// [{ id: '@ossy/tool/doc', name: 'Tool Doc', fields: [...] }, ...]

Primitives

The platform is built around file conventions called primitives. Each primitive is a file with a specific naming pattern that the build pipeline auto-discovers.

→ See PRIMITIVES.md for the complete reference.

| Primitive | Pattern | Purpose | |---|---|---| | Page | *.page.jsx | Routable UI (SSR + hydration) | | API | *.api.js | HTTP endpoint (any method) | | Task | *.task.js | Event-driven or scheduled async work | | Action | *.action.js | Named intent, auto-exposed at POST /actions | | Integration | *.integration.js | Third-party client connected at startup | | Email | *.email.jsx | Transactional React email template | | Component | *.component.jsx | Injectable UI fragment | | Resource | *.resource.js | Custom document-type schema | | Aggregate | *.aggregate.js | Event-sourced domain object | | Startup | *.startup.js | One-time boot hook |

Request lifecycle

Incoming request
  │
  ├─ POST /actions  ──► ActionService.invoke() ──► TaskService.invoke() ──► task.run({ payload, sdk, log, integrations, req })
  │
  ├─ Match API route    ──► api.handle(req, res)
  │
  └─ Match page route   ──► page.render(props) ──► HTML response

Requests that do not match an API route or page route receive 404 Not Found.

Related packages

| Package | Purpose | |---|---| | @ossy/app | Build pipeline — discovers primitives, bundles them, writes manifest.json | | @ossy/event-store | Event sourcing primitives (Aggregate, EventStore) | | @ossy/email | Email renderer and email.integration.js | | @ossy/observability | Structured logger and metrics | | @ossy/router | URL matching used by the platform server |