Platform API

Fastify TypeScript (strict) Prisma + PostgreSQL Azure Container Apps Mastra (AI Runtime) OpenAPI Zod Entra ID + API Keys

What It Does

The Platform API is the center of the SC ecosystem. Every tool, every agent, every data request routes through here. It handles authentication, authorization, and routing — connecting each consumer to exactly the data it's permitted to see, from the right source, in a consistent format.

It's built as a monorepo with three packages using hexagonal architecture — the package boundary is the architecture boundary:

@sc/core — Framework-free domain layer. All business logic, integrations, services, and schemas. Never imports HTTP frameworks or LLM SDKs (enforced by ESLint). Every service method takes ctx: { tenantId, principal, logger } as first argument.
@sc/platform-api — Fastify HTTP adapter. Thin routes calling core services; framework coupling isolated here.
@sc/orchestration — Mastra agent runtime. Tools are thin wrappers that call the same core services the HTTP routes do.

Key Design Decision

Multi-tenant from day one. Every domain table has tenantId. Queries that don't filter by tenant are bugs. Per-tenant variation (provider selection, credentials) lives in factories. When proactive agents arrive, they inherit this same security model — no new plumbing.

Two Deployables, One Codebase

The Platform API ships as two container deployments from a single codebase:

HTTP API

The REST API that all tools call. Serves telemetry, assets, work orders, and other data. Live OpenAPI spec for every endpoint.

RESTful endpoints via Fastify
Tenant + role-based auth on every request
Rate limiting and request logging
Auto-generated OpenAPI documentation

AI Runtime

The Mastra-based agent runtime that powers Ask Ricky and will power proactive agents. Same codebase, same auth, separate scaling.

Mastra agent framework
Anthropic Claude as the LLM
Tool definitions scoped per caller
Scales independently of the HTTP API

📸 Screenshot needed: Platform API architecture or OpenAPI docs

The Platform API OpenAPI documentation showing available endpoints.

Integration Catalog

The Platform API connects to external systems and normalizes their data into a consistent format. Per-tenant configuration controls which integrations are active.

Integration	Type	What It Provides
Murphy M-Link	IoT / Telemetry	Live compressor sensor data — pressures, temps, RPM, fault codes
Detechtion Enbase	Equipment Monitoring	Equipment health metrics, normalized alongside M-Link
Samsara	GPS / Fleet	Real-time vehicle locations, route history
NetSuite	ERP	Work orders, assets, inventory (migrating to Data Hub)
FieldAware	Field Service	Work order status, time/labor, field notes

Who Consumes It

Every user-facing tool in the ecosystem gets its data through the Platform API:

💬

Ask Ricky

AI chat gets telemetry, work orders, and knowledge base access

📊

Ops Dashboard

Fleet map, equipment status, work order views

✅

Hawkeye

Approval workflows and org data

⚙️

Platform Admin

Tenant and integration management

Security Model

The Platform API enforces the ecosystem's permissions and scoping model. For the full deep-dive, see the dedicated Permissions & Scoping page.

Two Types of Caller

Caller	Auth Method	How It Works
Humans	Entra ID (Bearer JWT)	Token identifies the person; DB User row determines tenant + role. No API keys for humans, no dev fallback in any environment.
Machines (agents, connectors)	`sk_` API Keys	Opaque bearer token, hash-matched to ApiKey row. Binds caller to tenant + carries scopes as ApiKeyScope rows.

Authorization Guards

Multi-tenant isolation — every request scoped to a tenant; cross-tenant data access is impossible
Role hierarchy — MEMBER → TENANT_ADMIN → SUPER_ADMIN. Each route chooses exactly one guard.
~10 scopes — Telemetry.Read, KnowledgeBase.Read, Assets.Read, WorkHistory.Read, Agent.Run, Directory.Read, FleetLocation.Read, etc.
AI tool scoping — when the AI Engine runs, the caller's scope profile determines which tools the agent can see and use
Per-tenant integration config — each tenant can have different external systems enabled via Platform Admin
Full request logging — every API call tracked for audit

Administration

The Platform API is configured and monitored through Platform Admin, which provides:

Tenant creation and management
Integration configuration per tenant
API key management
Agent tool configuration