Skip to content

Internal API

The Internal API is the private backend surface for Vibrant's internal operations, manufacturing lines, administrative tools, estate maintenance technicians, and automated back-office workers.

It is completely isolated from public and customer portals, running with dedicated network boundaries, secrets, and database credentials.

What It Does

  • Site Maintenance & Field Operations: Staff tools to conduct and edit property walkthroughs, capture inspection media, manage preventive maintenance schedules, record service completions, and triage work items.
  • Manufacturing & Hardware Provisioning: Enrolls physical devices, binds serial numbers to cryptographic gateway keys, and coordinates factory line QA tests.
  • Support & Administration: Privileged actions such as device resets, account repairs, and administrative audit inspection.
  • Invoicing & Accounting Automation: Ingests vendor bills via email, extracts line items from receipts (using vision/OCR models), syncs corporate Amex cards via Plaid, reconciles Connecteam worker hours, and generates customer invoices.

Identity & Authorization

Access requires authentication through Keycloak's isolated internal realm:

  • Human Staff: Log in via vibrant-internal-web (MFA/TOTP required). Keycloak assigns internal_staff, minting tokens with role: internal_api_role.
  • Role-Gated Actions: Specific operational capabilities require corresponding realm roles:
  • site_maintenance_admin: Managing maintenance schedules, conducting staff walkthroughs, and editing work items.
  • internal_manufacturing / internal_manufacturing_admin: Hardware enrollment and physical device deletion.
  • internal_admin: Platform-wide administrative overrides.
  • Dual-Transport Pattern:
  • Internal PostgREST (port 3600): Staff apps query views in internal_api (e.g. walkthroughs, walkthrough_media, bills) protected by RLS and the staff role. Anonymous access (internal_anon) has zero grants and fails closed.
  • Internal FastAPI (port 3500): Executes writes, multi-step workflows, file presigning, and OCR/AI pipelines.
  • Background Workers: In-process queue processors connect directly via asyncpg using internal_api_login and private *_for_worker functions.

Invoicing & Maintenance Privacy

Underlying domain storage tables (invoicing.*, site_maintenance.*) remain private. They are never exposed directly to public clients or granted to public application roles. Reads and actions flow through internal_api.* views and RPCs granted explicitly to internal_api_role.

Technical Pointers

  • Service Code: src/vibrant_platform_internal_api/
  • Entrypoint: vibrant_platform_internal_api.main:create_app
  • Operational Modules: src/vibrant_platform_internal_api/modules/ (site_maintenance, walkthroughs, work_items, schedules, assets, invoicing)
  • Background Jobs: src/vibrant_platform_internal_api/jobs/
  • Keycloak Reconciliation: infrastructure/local/keycloak/reconcile-internal-access.sh
  • Database Schemas: internal_api, site_maintenance, media, and invoicing in infrastructure/db/schema.sql