Platform Architecture

Vibrant Platform provides a shared backend for IoT devices, smart spaces, facility operations, billing, and AI agents.

To keep security airtight and systems modular, different audiences use dedicated API surfaces, while all applications share a single PostgreSQL database organized into domain-specific compartments (schemas).

                      [ Client Applications ]
     (Public Apps)       (Enterprise Portal)     (Internal Ops & Tools)
           │                      │                         │
           ▼                      ▼                         ▼
┌────────────────────┐ ┌────────────────────┐    ┌────────────────────┐
│   Public Surface   │ │ Enterprise Surface │    │  Internal Surface  │
│ ┌────────────────┐ │ │ ┌────────────────┐ │    │ ┌────────────────┐ │
│ │  FastAPI :3400 │ │ │ │  FastAPI :3800 │ │    │ │  FastAPI :3500 │ │
│ └────────────────┘ │ │ └────────────────┘ │    │ └────────────────┘ │
│ ┌────────────────┐ │ │ ┌────────────────┐ │    │ ┌────────────────┐ │
│ │ PostgREST :3300│ │ │ │ PostgREST :3850│ │    │ │ PostgREST :3600│ │
│ └────────────────┘ │ │ └────────────────┘ │    │ └────────────────┘ │
└─────────┬──────────┘ └─────────┬──────────┘    └─────────┬──────────┘
          │ (api)                │ (enterprise_api)        │ (internal_api)
          └──────────────────────┼─────────────────────────┘
                                 ▼
                     ┌──────────────────────┐
                     │ PostgreSQL Database  │
                     │  - Exposed Schemas   │
                     │  - Domain Storage    │
                     └──────────────────────┘

Core Concepts

1. The Dual-Transport Model

Behind the API gateway, each surface provides two complementary ways to interact with data:

PostgREST (Fast Reads & Simple Queries): Translates REST requests directly into PostgreSQL queries. Because PostgreSQL enforces Row-Level Security (RLS) per user token, PostgREST allows web and mobile apps to safely query views without custom backend endpoints.
FastAPI (Complex Workflows & Integrations): Handles business logic that cannot live purely in SQL: user onboarding, payment processing, file presigning for object storage (S3/RustFS), third-party webhooks, and asynchronous background jobs.

2. Private Storage vs. Public Contracts

Database tables live in private domain schemas (devices, accounts, places, invoicing, etc.) and are never exposed directly to web clients. Instead, each tier has a dedicated contract schema with secure views and stored procedures (RPCs): * api — Public mobile and customer contracts. * enterprise_api — Enterprise facility customer contracts. * internal_api — Internal operations and staff contracts.

Surfaces & Ports Reference

Surface	Audience	FastAPI Service	PostgREST Schema & Port	Keycloak Client & Role
Public	Homeowners, mobile apps, contractors	`vibrant_platform_api` (port 3400)	`api` (port 3300)	`vibrant-mobile` / `role=authenticated`
Enterprise	Estate-care clients (Internal clients or combine with public in future)	`vibrant_platform_enterprise_api` (port 3800)	`enterprise_api` (port 3850)	`vibrant-enterprise-web` / `role=enterprise_portal_role`
Internal	Internal staff, maintenance technicians, manufacturing, billing ops	`vibrant_platform_internal_api` (port 3500)	`internal_api` (port 3600)	`vibrant-internal-web` / `role=internal_api_role`
Agents	Automated AI agents & tooling	`vibrant_platform_agent_manager` (port 8080) `agent_workspace` (port 8081) `mcp` (port 3700)	N/A (uses private SQL roles)	`vibrant-internal`

Architecture Guides

Auth & RPC Layers — How tokens, Keycloak realms, and database roles map from the edge to SQL.
Enterprise API — Facility maintenance, asset tracking, walkthroughs, and media workflows.
Internal API — Staff operations, site maintenance & walkthroughs, hardware provisioning, and invoicing.
Modularity & Schemas — PostgreSQL schema boundaries and rules for table exposure.
Background Jobs & Workers — How async workers access PostgreSQL via *_for_worker functions without HTTP proxies.
Source Inputs & Provenance — Architectural heritage and legacy system consolidation notes.