Skip to main content

Platform Architecture

Last reviewed: 2026-06-13
Maintained by: Engineering

ZGRID is built as one shared operating layer for managers, residents, technicians, and platform administrators.

The platform is intentionally split into a small number of product surfaces that all rely on the same backend contract, shared domain model, and environment-managed integrations.

Architecture at a Glance​

At a high level, ZGRID is organized into five layers:

  1. Public product surface: the landing site explains the product and captures inbound interest.
  2. Internal operating surfaces: Manager Desk and Back Office support day-to-day platform and building operations.
  3. Mobile surface: ZGRID Mobile keeps residents and technicians connected to the same live operational state.
  4. Shared platform core: the API enforces auth, business rules, tenancy, workflows, and integrations.
  5. Shared contracts and utilities: workspace packages keep the web and mobile surfaces aligned on one product language.

Product Surfaces​

Landing​

apps/landing

The landing site is the public-facing product layer. It presents the ZGRID story, localized marketing content, and a server-backed inquiry flow.

Manager Desk​

apps/manager-desk

Manager Desk is the main operating workspace for manager organizations. It brings together issues, service requests, communication, documents, building decisions, onboarding, legal settings, and financial visibility.

Back Office​

apps/back-office

Back Office is the platform control layer for super_admin users. It is where platform-wide organizations, subscriptions, feature entitlements, legal profiles, audit visibility, and privacy-request processing are managed.

ZGRID Mobile​

apps/zgrid-mobile

ZGRID Mobile is the resident and technician surface. It keeps community reporting, notifications, documents, service flows, and technician job work close to the same backend state as the internal web workspaces.

Shared Platform Core​

API​

apps/api

The API is the shared operating core behind every ZGRID surface.

It is responsible for:

  • authentication and session handling
  • role, tenant, and organization scope enforcement
  • workflow orchestration for issues, onboarding, communication, billing, and admin controls
  • data access and integration boundaries
  • shared validation and response behavior across clients

This means ZGRID does not treat business rules as a front-end concern. Internal web apps and mobile flows stay aligned because the server contract is the same for all of them.

Database​

database

The database is PostgreSQL-based and migration-driven. It stores the shared platform state behind auth, buildings, operations, subscriptions, privacy, audit, and integration workflows.

Shared Packages​

ZGRID uses workspace packages to reduce duplication and keep product behavior aligned across apps.

@zgrid/api-client​

Shared typed API contracts and request helpers used across web and mobile clients.

@zgrid/validation​

Shared validation schemas for repeated product flows such as onboarding and issue reporting.

@zgrid/web-shell​

Shared internal web-app shell utilities, including the small-screen guard and standard shell-level system states.

@zgrid/monitoring​

Shared browser-side monitoring helpers for internal web surfaces.

Integration Layer​

External services are connected through the API or hosted platform configuration rather than being treated as independent product systems.

Current integration areas include:

  • email delivery
  • attachment storage
  • monitoring
  • push delivery
  • subscription billing
  • optional uptime visibility

The public docs describe these integrations by purpose and boundary, not by exposing credentials, dashboards, or private infrastructure detail.

Core Architectural Principles​

One backend contract​

Managers, residents, technicians, and administrators use different interfaces, but they rely on the same server-side business rules.

Shared product language​

Where a feature exists across more than one surface, shared contracts and shared validation should define the language first.

Tenant and role safety​

Authorization, tenancy, and scope checks belong in the API, not only in the UI.

Optional integrations​

Monitoring, billing, storage, and delivery integrations are environment-controlled so local work can stay lightweight while hosted environments can enable the full platform shape.

Public-safe documentation​

Architecture docs should explain how ZGRID is shaped and why, while avoiding secrets, private URLs, internal account identifiers, or abuse-oriented operational detail.