Feature Overview & Roadmap
The original brief, what we've built so far, and what's coming next — a single source of truth for internal stakeholders and prospective tenants.
In this document
- 1 The Brief & Vision
- 2 What We've Built
- 3 What's Coming Next
- 4 Strategic Architecture Layers
The Brief & Vision
The original problem we set out to solve, and the principles guiding every decision since.
The original brief
Build a modern, cloud-based operating system for parking operators — one platform that can run an entire estate (non-gated lots, gated sites, on-street zones and hybrid models) without the patchwork of legacy tools operators are forced to stitch together today.
It had to be genuinely multi-tenant from day one — many operator brands on a single deployment, with strict data isolation, per-tenant payments, and the ability to settle funds at the site level for landlord and JV arrangements.
Guiding principles
- Parker-first: every flow must work on a phone in under 30 seconds, with no app install.
- Operator-grade: configuration without code — tariffs, schedules, content and access live in the UI.
- Multi-tenant by design: isolation, branding, currency, timezone and legal docs per tenant.
- Honest pricing: itemised tax, fees and caps — or a single gross total, the operator's choice.
- Auditable: every state change tracked; refunds and modifications leave a trail.
- Composable integrations: Stripe, enforcement APIs and outbound webhooks rather than walled gardens.
Who it's for
- Parking operators — running multi-site estates across non-gated, gated and on-street parking.
- Landlords & JV partners — who need clean per-site settlement and transparency.
- Enforcement teams — who need fast plate-based lookups and grace-period awareness.
- Finance & ops staff — who need reconciliation, reporting and timezone-aware data.
- Parkers — who just want to scan, pay and get on with their day.
What We've Built
The current state of the platform — every shipped capability, organised by area.
Multi-Tenant Architecture
ShippedOne platform, many operators, full data isolation.
- Super admin console — manage every tenant, their Stripe connection, master T&Cs and global settings.
- Tenant admins — scoped to their own tenant — auto-locked tenant context, no switcher.
- Operators / users — day-to-day staff with restricted operational access.
- Per-tenant branding — logo, currency, timezone, country, master legal documents.
- Stable internal references — T-0001 / L-0001 / Z-0001 plus optional external refs.
- Role-gated UI & routes — navigation filtered per-role; tenant data isolated server-side.
Locations & Sites
ShippedEvery car park, modelled the way the operator runs it.
- Site types — non-gated, gated, on-street and hybrid — each with the right defaults.
- Rich parker content — instructions, rates summary, operating hours, site photos, after-hours contact, arbitrary extra info.
- Compliance content — T&Cs from master, URL, uploaded PDF or inline HTML; privacy from master or URL.
- Enforcement controls — grace period, max stay, optional LPR notice, optional enforcement API URL.
- Public listing link — auto-resolved via tenant URL template, or overridden per site.
- Geocoding fields — address, suburb, city, state, postcode, country, lat/lng and timezone.
Zones
Shipped- Capacity tracking per zone.
- Internal and external references for downstream system mapping.
- Per-zone instructions, status and colour for visual identification.
- Used by session QR codes, permits and tariff scoping.
Tariffs & Pricing Engine
ShippedFrom simple flat rates to full week-tiled schedules — without writing code.
- Five tariff types — stopwatch, fixed duration, daily flat, free, and week-tiled schedule.
- Schedule builder — drag-and-drop weekly grid with priced and closed blocks, flat + repeating incremental pricing steps, wall-clock or session-elapsed resets, and early-bird/morning/evening labels.
- Templates — common patterns available as one-click starters.
- Daily caps — wall-clock reset at a chosen time or rolling 24h from session start.
- Free time, minimum charges, grace periods, max duration.
- Tax handling — configurable label (GST / VAT / Sales Tax), rate, and inclusive/exclusive treatment.
- Convenience fees — flat per-transaction fee with custom label.
- Multi-currency — AUD, NZD, USD and others (ISO 4217).
- Scheduled activation — queue a new tariff to swap in automatically at a future time.
- Price display — itemised breakdown or single gross total, per tenant or per tariff.
Parking Sessions
ShippedThe heart of the platform — every stay, every plate, every dollar.
- Session types — casual paid, casual free, validated, permit, staff, contractor, manual-admin.
- Lifecycle states — pending payment → active → expired / stopped / cancelled, with full audit history.
- Human-readable refs — PKS-XXXXX reference per session for support and reconciliation.
- Plate normalisation — case- and whitespace-insensitive lookups for enforcement.
- Extensions & stops — parkers and operators can extend or end a session early.
- Receipts & reminders — automatic email receipts and expiry reminders.
- Refunds — full or partial, with reason tracking and audit trail.
- Session timeline — every state change recorded as SessionEvents.
QR Hub
ShippedOne place to manage every QR code the operator hands a parker.
- Unified dispatcher — session start, promo redemption, permit issuance and gate access flow through a single /q/:token endpoint.
- Token-based short URLs — opaque slugs that resolve server-side — safe to print on signage.
- Validity windows — valid-from / valid-until and max-scan caps for time-limited campaigns.
- Per-tenant or per-location scoping — with display codes for manual entry where useful.
- Downloadable artwork — rendered PNG for print, plus internal labels and descriptions for ops.
- Scan analytics — running scan counts and status (active / paused / expired / archived).
Promo Codes
ShippedFlexible discounts for staff, validations and campaigns.
- Four discount types — percent off, flat amount off, free minutes added, and 100% free.
- Scope control — tenant-wide, specific locations, or specific tariffs.
- Usage limits — total cap and per-parker cap (by email or plate).
- Validity windows — active dates plus min/max session duration qualifiers.
- Manual entry or QR — codes can be typed by parkers or scanned from signage.
- Convenience fee waivers — optionally drop the per-transaction fee on redemption.
- Full redemption audit — every use recorded as a PromoRedemption with code and amount snapshots.
Payments & Payouts
ShippedStripe-native, with JV-friendly per-site overrides.
- Tenant-level Stripe connection — test / live modes, encrypted secret keys, built-in connection test.
- Per-location payment overrides — route funds to a landlord, JV partner or trust account at the site level.
- Application fees — percent or flat operator fee per session.
- Payee labels — human-readable payee names for finance and ops clarity.
- Apple Pay, Google Pay and cards — via Stripe checkout.
- Refunds & partial refunds — tracked against the original charge with reason codes.
Enforcement
Shipped- Grace periods configurable per site.
- Maximum stay enforcement to prevent abandoned vehicles.
- Optional LPR / ANPR notice for camera-enforced sites.
- Plate-based session lookups for officers and ground staff.
- Outbound enforcement API URL per site for downstream breach-notice providers.
Parker Experience
Shipped- Scan-to-pay flow — QR signage takes parkers straight to the right action on their phone — no app, no friction.
- Public landing route — /q/:token resolves server-side and dispatches to the correct action.
- Transparent pricing — clear breakdown of rate, tax, fees and total — or a single gross figure.
- Receipts by email
- Localised content — right currency, timezone and legal docs for each site.
Time, Timezones & Operating Hours
Shipped- Every tenant and site has its own timezone — no UTC confusion.
- Operator app timezone picker for finance reviews.
- Three display modes for operating hours: always open, scheduled per-day, free-text.
- Schedule engine is fully timezone-aware for tariff blocks and daily caps.
Integrations & Webhooks
Shipped- Outbound webhooks — subscribe to session.created, paid, expired, stopped, cancelled and refunded events.
- HMAC-signed payloads — shared secret per webhook for tamper-proof delivery.
- Delivery status tracking — last delivery time, status and failure counters per endpoint.
- Enforcement API hooks — per-site outbound URL for downstream enforcement systems.
- Stripe Connect — for tenant and per-location payouts.
Reporting & Insights
Shipped- Live dashboard with active sessions, revenue, occupancy and trend lines.
- Per-location breakdown of utilisation and revenue.
- Session history with filters by date, status, payment method, plate and site.
- Exportable reports for finance reconciliation.
- Full SessionEvent audit log for compliance and dispute resolution.
What's Coming Next
Identified gaps, near-term work, and the longer-term roadmap. Each item is tagged by status.
Parker Web App (v1)
ShippedThe end-user experience — scan, pay, park. Live against Sudima Auckland Airport.
A web-only parker experience (no app install). Opens from a QR or link, captures plate + email, verifies with a one-time code, takes payment, and confirms. Now live with end-to-end Stripe checkout, promo code redemption, scheduled expiry reminders, automatic receipts on expiry, and a self-service manage-session screen.
v1 scope — shipped
- Site landing flow — /at/:site_code → welcome → plate → rates → pay → confirmed session screen.
- Fixed-duration tariffs — preset duration tiles with itemised or gross-total pricing per tenant.
- Email verification — 6-digit SendGrid OTP with 90-day trusted-device token in localStorage.
- Stripe Payment Element — card, Apple Pay, Google Pay, Stripe Link — per-tenant or per-location Stripe keys.
- Promo codes at checkout — live redemption flow with PromoRedemption audit log.
- Manage session — live countdown, extend on fixed-duration tariffs (top-up PaymentIntent), session detail card, location info modal.
- Self-expire on countdown end — parker page triggers expireSessionNow the moment the timer hits zero — no waiting for the 5-min cron.
- Receipts & expiry reminders — scheduled SendGrid reminder before expiry, branded receipt email on session end.
- Per-tenant branding — logo, primary/secondary colours, master T&Cs and privacy URLs flow through every parker screen.
Identified gaps & near-term improvements
Identified gapSurfaced during platform review — work scoped for the next cycles.
- Reporting exports — CSV/XLSX exports with finance-ready columns (payout, fee, tax, refund).
- Audit search — fast filter/search across SessionEvents for dispute resolution.
- Tenant-facing docs portal — selectively expose pieces of this documentation to tenants in-app.
- Granular permissions — move beyond admin / tenant_admin / user to per-action roles.
- Bulk operations — bulk session refunds, bulk tariff swaps, bulk promo issuance.
- Better empty / error states — across QR Hub, Promo Codes and public landing — first-run polish.
Parker Web App — v1.5
Next upStopwatch tariffs, saved cards, more tariff types in the parker UI.
Stopwatch & long stays
- Stopwatch tariff support (price unknown at start, captured on stop).
- Stripe SetupIntent + off-session charge pattern — modern, no 7-day auth expiry, sets up saved-card UX for free.
- $0/$1 pre-auth fallback when a tenant prefers live-auth fraud protection.
- Retry policy on capture failure (default: 3 retries over 24h, then email parker a payment link).
- Tokenised parker history page — 6-month token from receipts, shows past + active sessions.
- Stopwatch + daily_flat + schedule + free tariff types in the parker UI.
White-label tiers (planning)
- Bronze — colour + logo on parker app, default platform domain. (Live today — every tenant gets brand colours + logo through the parker flow.)
- Silver — + custom email from-address & per-tenant templates.
- Gold — + custom domain (tenant points CNAME, we auto-provision certs).
- Operator app is never white-labelled. Per-site branding override available for tenants running multiple brands.
Explicitly deferred
- SMS / mobile contact — ✅ now shipped via WebSMS (see Parker communications). No longer deferred.
- Parker accounts / cross-device login — localStorage + tokenised history covers the use case.
- Hotel self-serve validation flow — reception types into operator app for now.
- BNPL (Afterpay / Klarna) — wrong price band; revisit for permit subscriptions only.
- Native mobile app — web is the strategy.
Permits & subscriptions
In progressLong-stay, monthly parkers and validated tenants.
Phase A — shipped. Permit templates, manual issuance, list/detail UI, suspend/cancel/reinstate, related sessions on the permit detail.
Phase B — coming next.
- Recurring billing for monthly / weekly subscriptions (Stripe).
- Auto-renew flow with operator-configurable reminder emails (N hours before expiry).
- Event / group permits — bulk-issue (e.g. 50 plates for a conference) with one validity window, managed as a group.
- Permit issuance via QR scan (parker self-service from signage).
- Enforcement-aware: permits suppress breach notices for the relevant plate within their validity window (see ePRO integration below).
ePRO integration & inherited capabilities
Next upBoundary contract with our sister enforcement app — and the gaps it surfaced that belong in ParkOS.
ePRO is the rules engine — it consumes LPR camera reads and generates violations. ParkOS is the system of record — sessions, permits, whitelists and blockouts. ePRO should ask ParkOS one question per camera read: "is this plate valid here, right now?" — and ParkOS should be the single source of truth that answers it.
Capabilities to add to ParkOS (surfaced by ePRO review)
- Plate whitelists — entitlement to park without a paid session, scoped by location, duration and reason. New entity under Access.
- Quick-whitelist QR — guest scans a QR, plate is whitelisted for a fixed duration (new QR Hub type).
- Enforcement blockouts — scheduled windows where enforcement is paused (e.g. cleaning contractor 6–8am Tue). Location-level.
- Universal plate search — global ⌘K dialog finding every Session, Permit and Whitelist for a plate across all sites.
- checkPlateValidity backend function — single authoritative endpoint returning { valid, source, expires_at }. The contract ePRO consumes.
Patterns to borrow from ePRO (when Permits Phase B lands)
- Recurring permit auto-renewal cron (ePRO's renewRecurringPermits).
- Permit expiry reminder emails with configurable lead time.
- Event/group permit pattern — permit_group_id + group-level management UI.
Explicitly NOT copying from ePRO
- Custom Client / ClientUserInvite / dual-Layout portal — ParkOS already has a cleaner version via Tenant + RoleGate + Base44 invites.
- SendGrid invite tokens & webhooks — superseded by Base44's built-in inviteUser.
- GMP / Enforcify connectors — ePRO's domain, not ours.
- PageView analytics, VersionChecker, public showcase pages — premature for ParkOS.
- Plate Recognizer OCR / camera scan — ePRO owns the cameras.
Migration note: ePRO currently maintains its own permit list (predates ParkOS Permits). Long-term, ePRO retires its permit store and reads from ParkOS via checkPlateValidity. This is a planned migration, not immediate work.
Gated sites — auto-vend entry, tap-to-pay exit
Next upBoom-gated car parks operated the way high-throughput sites actually flow.
The operating model is dumb entry, smart exit. Entry boom auto-vends on presence loop — no cloud call, no decision, the car always gets in. Entry LPR captures the plate silently and opens an anonymous journey in the cloud. At exit, LPR reads the plate, cloud matches the journey, calculates the fee, and the parker either vends free (within grace) or taps to pay at the exit POS terminal. Pay-on-phone is still supported as a secondary path using the same Parker Web App that runs at Sudima today.
The architecture is cloud = brain, edge = physical bridge, hardware = execution. The edge box is a thin Linux gateway that proxies devices and survives short outages. All tariff calculation, journey matching, fee calculation, payments and audit live in the cloud. The edge is never the system of record.
LPR-misread fallback (a designed safety net, not an error case)
- If exit LPR misreads or fails, presence loop still detects the vehicle.
- Exit POS prompts a $0 pre-auth tap — card is captured but no charge is taken.
- Boom vends within ~10 seconds. Parker is never trapped at the barrier.
- Cloud creates an UnmatchedExit record with image snapshots and the captured card token.
- Operator reconciles later via a dedicated ops queue — match to entry, capture the real charge if owed, or release the auth if within grace.
Reuse of existing platform primitives
- apiComplianceCheck is the per-plate decision contract — extended for exit-time fee calculation as resolveExitDecision.
- Existing Tariff engine drives fee calculation unchanged. No pricing logic at the edge.
- Existing Stripe payment-intent pattern extends to Stripe Terminal / Windcave (capture_method=manual for zero-auth flow).
- Webhooks act as the cloud→edge command channel until persistent WSS is justified.
- SessionEvent audit shape extends naturally into GateEvent for camera reads, vends and loop transitions.
- The same Parker Web App used at Sudima today is reused for pay-during-stay and pay-at-exit-by-QR — no new parker UI required.
New entities & endpoints (scoped, not yet built)
- Journey — first-class entry-to-exit lifecycle record per vehicle, distinct from the paid Session layer.
- UnmatchedExit — LPR-misread reconciliation queue for ops review.
- EdgeDevice, Gate, GateEvent, DeviceCredential, EdgeHeartbeat — physical-world entities mirroring the cloud model.
- resolveExitDecision — single endpoint returning vend/charge/unmatched + fee + journey context.
- createUnmatchedExitAuth / captureUnmatchedExitCharge — zero-auth then manual capture for the misread fallback.
- edgeProvision / edgeHeartbeat / edgeIngestEvents / gateCommand — the cloud↔edge contract.
Phased delivery
- Phase 1 — gate-QR retrofit for brownfield sites (cloud lifts an existing relay, no LPR, no edge box yet).
- Phase 2 — pilot edge bridge with POS on day one: Getapark NZ, one site, LPR + barriers + IO controller + Windcave POS terminal. Tap-to-pay-at-exit is the primary parker path from launch.
- Phase 2.5 — fleet management foundations (device provisioning, heartbeat, cert rotation, remote restart).
- Phase 3 — promote Journey to a full engine: lane activity console, capacity engine, journey reports.
- Phase 4 — permit, whitelist and validated-parker flows at the gate (all handled by resolveExitDecision branches).
- Phase 5 — SIP intercom + remote concierge integration.
Connectivity & remote management — Tailscale
- Tailscale (WireGuard mesh) is the secure management & support plane — SSH to edge, camera/router/switch/POS admin UIs, intercom config.
- Edge gateways run tailscaled and act as subnet routers, exposing peripheral devices that can't run Tailscale themselves — no public-internet exposure of onsite hardware.
- Strict tag/ACL model: tag:edge-gateway, tag:site-<slug>, tag:env-production, plus role tags (ops / developer / support / partner-installer). Deny-by-default, least privilege, audit log mirrored into our own trail.
- Three planes kept separate: app control (edge ⇄ cloud MQTT/WebSocket), management (Tailscale), local resilience (edge agent + IO controller). A Tailscale outage costs us remote admin reach — parking keeps working.
- Build-vs-buy unambiguously buy. Swap-out option preserved for customers mandating their own VPN.
Degraded-mode (simpler than initially scoped)
- Entry never needs the cloud anyway — auto-vend always works.
- Exit during outage: per-location policy of fail_open (default — vend everyone, reconcile later, small revenue loss accepted) or intercom_only (high-security sites where free egress is unacceptable).
- POS terminals (Windcave especially) store-and-forward transactions natively during short outages.
- All edge events buffered locally and replayed idempotently on reconnect — no data loss.
Recommended hardware shortlist (under evaluation)
- POS terminal: Windcave (NZ-native, our preferred vendor) — Stripe Terminal as US/AU alternative.
- Router / connectivity: Teltonika industrial routers (compact, dual-SIM, strong remote management) — Peplink, Fortinet, Meraki, Cradlepoint as alternatives.
- Edge gateway: Advantech UNO/ARK or fitlet industrial mini PCs — OnLogic, AAEON, Neousys as alternatives for harsher environments.
- IO / gate controller: Advantech WISE series, Moxa IO modules, ICP DAS — Modbus TCP or HTTP/MQTT capable.
- LPR cameras: Milesight or Hikvision (AU/NZ market defaults) behind a vendor-abstracted integration layer.
- Switching: Ubiquiti UniFi managed PoE for indoor sites, industrial DIN-rail switches for cabinet deployments.
Edge software & AI-assisted build approach
- Edge software stack locked — Ubuntu Server LTS + Docker + Tailscale + SQLite + TypeScript/Node.js edge-agent (same language as cloud, shared event-shape types).
- Modular device driver pattern — vendor-swap a camera, controller or POS terminal without touching the core. Initial drivers: Advantech WISE, Modbus TCP, HTTP relay, Milesight/Hikvision LPR webhook, Windcave POS, Stripe Terminal.
- Edge MVP ships as software first — simulator on a developer laptop, then real Tailscale-connected hardware, then real gate controller, then LPR, then Lane Activity Console, then POS. Edge software risk decoupled from pilot-site install risk.
- AI is a build-time tool — drivers, adapters, simulators, log analysis, Docker/CI configs, internal docs. AI never sits in the runtime gate-command path.
- Hard guardrails: gate commands are deterministic + permissioned + audit-logged + authenticated against DeviceCredential. AI-generated code merges only via human-reviewed PR. Production credentials never leave the cloud — AI tooling sees mock/staging only.
- Phase 6 AI inference at the edge (LPR, ReID, vehicle signature) is purpose-built CV models with deterministic outputs — not language-model agents. No 'AI brain' container ever runs on the edge.
- Fleet management deferred until ≥3 sites. Pilot uses manual SSH-over-Tailscale + shell script. At 3+ sites: GitHub Container Registry + custom controlled updater. Heavyweight tools (Balena, Mender, Greengrass) re-evaluated at ~10 sites.
Full operating model, sequence diagrams, contract specs and open questions live in docs/GATED_SITE_ARCHITECTURE.md. Vendor-neutral architectural principles are in docs/GATED_EDGE_STRATEGY.md. Edge software architecture & AI-assisted build workflow in §10 of the architecture doc.
Vehicle Session Integrity — rising above the noise
FutureThe differentiator. Every gated system in market builds to the happy path. We build to the unhappy path.
Traditional gated parking assumes entry plate read = exit plate read. When that fails — and it fails in 1–2% of sessions even with the best LPR — the operational fallout is disproportionate: blocked exit lanes, queue escalation, panicked customers, intercom overload, revenue leakage, false enforcement events. We treat vehicle session continuity as a first-class architectural concern, not a tuning problem.
The licence plate stays the primary identifier; the vehicle signature (make, model, body type, colour, ReID visual embedding, direction, expected duration) becomes the secondary identity. AI engages only when LPR is uncertain — 98–99% of exits never touch the integrity layer. Worst case it can ever do is "no improvement on today" because the existing zero-auth UnmatchedExit flow is always the floor.
Confidence-driven exit decision
- Signals weighted: plate match, near-plate match, colour, make/model, body type, ReID embedding similarity, direction validity, expected duration.
- Confidence 90–100 → silent auto-vend.
- Confidence 70–89 → auto-vend + audit flag for ops review.
- Confidence 50–69 → soft-exception on POS: vehicle thumbnail shown, parker confirms 'yes, that's me' in one tap.
- Confidence < 50 → falls through to existing zero-auth + UnmatchedExit reconciliation.
- Decision window: 300–800ms. Never block a lane while debating signature similarity.
Three sub-phases
- Phase 6a — signature capture (passive, ~3–4 weeks). Every entry generates a VehicleSignature linked to the Journey. No decisioning yet — just builds the evidence base. Vehicle thumbnails + attributes immediately visible in ops UI.
- Phase 6b — active reconciliation (~6–8 weeks). resolveExitDecisionWithSignature engages on plate-mismatch / low-confidence exits. Failed-exit rate at pilot drops from ~1–2% to ~0.1–0.3%. Intercom calls collapse.
- Phase 6c — spatial vehicle intelligence (12+ weeks, future). Multi-camera ReID, per-bay occupancy from aerial views, internal path reconstruction, abandoned-vehicle / wrong-way / dwell-anomaly detection.
AI stack (vendor-abstracted from day one)
- Vehicle detection: YOLOv11 / RT-DETR — detect, crop, lane positioning, directional vector.
- In-stream tracking: ByteTrack / OC-SORT — identity continuity within a single camera.
- Re-identification (the core signature tech): FastReID / TransReID / VehicleNet (VeRi-776 pretrained) — embed vehicles into a vector space for cross-camera + cross-time matching.
- Attribute extraction (make/model/colour): Plate Recognizer / Rekor / OpenALPR or self-hosted equivalents.
- Inference at the edge — N100 mini PCs for single-stream entry/exit, Jetson Orin Nano for multi-stream, Hailo-8 as the perf/watt dark horse for distributed smart-camera nodes.
New entities (scoping only — not yet built)
- VehicleSignature — per-journey record with attributes + opaque embedding vector. Linked to Journey.
- SignatureMatch — each integrity-layer evaluation, with signal breakdown. For audit, training and tuning.
- JourneyReconciliation — when a journey closes via signature instead of plate, records the original misread, matched plate, score, and reconciler. Feeds operator reports + LPR vendor SLA tracking.
Positioning — what this is NOT
- Not 'AI surveillance' — we say 'intelligent session recovery'.
- Not 'smart parking AI' — we say 'vehicle session continuity'.
- Not 'computer vision platform' — we say 'operational resilience' and 'graceful degradation when LPR struggles'.
- Signatures stored against journey IDs, not parker identity. Embeddings are opaque (cannot reconstruct image). Auto-purged when the journey closes + retention period.
This is the bit competitors don't do well. Once Phase 6b lands, our failed-exit rate at pilot sites should be an order of magnitude better than the incumbents — and that's the metric airport, hospital and premium-precinct procurement teams actually care about. Full architecture, confidence-scoring tables, risk register and AI stack in docs/GATED_SITE_ARCHITECTURE.md §7.
Visual Site Builder + AI Builder — drag-and-drop topology designer
In progressThe network topology IS the business config. Now with a prototype canvas, a Floor Plan layer, and an AI helper that builds layouts from natural language.
Every gated parking vendor we've evaluated configures sites through form hell — dozens of linked records describing where the gates are, which camera watches which lane, which zone nests inside which. It's slow, error-prone, and unintuitive when sites get re-organised (which is constant). A drag-and-drop canvas replaces this: the operator literally draws their car park (or describes it to the AI) and every gate, zone, camera, controller, POS and edge device falls out as a real entity behind the scenes.
Prototype shipped (super-admin only, Docs → Site Builder)
- Two-layer canvas — a Floor Plan layer (bay rows, drive aisles, entry/exit lanes, walls, building footprints) and a Network layer (site, zones, gates, LPR cameras, IO controllers, POS terminals, edge gateway) rendered on the same coordinate space.
- Drag-and-drop palette split by layer. Bay rows are parametric — count, single/double, orientation, bay kind (standard / accessible / EV / motorcycle / reserved), label prefix.
- Auto bay count — total bays summed across all bay rows, surfaced in the header. Zone capacity becomes derivable, not typed.
- Layer toggles in the toolbar — turn Floor / Network on or off independently. Designed to support a future 'Live state' layer in the same way.
- Live Ops mode — scripted simulation of a vehicle journey (entry LPR → guest zone → exit POS), with node states lighting up in real time. Foundation for the Lane Activity Console.
- Sudima Auckland Airport reference layout pre-loaded — full floor plan + network topology, exportable to JSON.
AI Builder (the differentiator)
- Plain-English prompts: 'Build a 40-bay office carpark with one entry, one exit, 4 EV bays, edge gateway in the corner' — the AI returns a complete floor plan + network topology + edges in one shot.
- Iterative refinement: 'Now add a permit-only staff zone on the left side' — the AI receives the current state and modifies it, preserving what's already on the canvas.
- Strict JSON schema contract — the AI must return well-formed nodes / edges / floor elements with the same shape as a hand-built layout. No free-text hallucinations.
- Built-in design rules baked into the prompt — site container first, LPR cameras near gates, IO controllers near gates, sensible bay/aisle dimensions, one edge gateway per site.
- Curated example prompts on first load to short-circuit the blank-canvas problem.
- History panel keeps the last 6 prompts + AI summaries for context.
What this unlocks (now and later)
- Today: super-admin sales tool. Walking a prospect through a drag-and-drop or AI-built site canvas is a category-different demo moment vs. incumbents whose UX is SaaS-from-the-90s.
- Soon: self-serve operator onboarding. New operator describes their site, AI drafts the layout, operator tweaks, hits 'commit' — entire Location + Zones + (future) Gates created in one motion.
- Mid-term: auto-derives the network plan (VLANs, Tailscale subnets, webhook endpoints), Journey topology (legal entry→exit paths, wrong-way detection), Capacity Engine graph (nested zone share-of-parent), install BOM (camera/gate/POS/switch-port counts).
- Long-term: Lane Activity Console (Phase 11c) — the canvas IS the live view. Same diagram, every node lights up with real-time state. One mental model from design → install → operations.
- Install drawing export (Phase 11d): PDF with dimensions, cable runs, device placement, BOM — the integrator deliverable.
Phased delivery (revised)
- ✅ Phase 11a — Prototype canvas with Floor Plan + Network layers, AI Builder, Live Ops simulation, Sudima reference layout. (Shipped, super-admin only.)
- Phase 11b — Persistence. Promote in-memory layout to a real SiteLayout entity. Bidirectional sync with Location / Zone records so editing the canvas updates the underlying entities and vice versa.
- Phase 11c — AI Builder v2. Vision input (upload a satellite image or hand sketch → AI traces it into a layout). Tenant-facing, with safety rails on entity creation.
- Phase 11d — Live operations overlay. Canvas becomes the Lane Activity Console once Phase 3 (Journey + Capacity Engines) lands.
- Phase 11e — Install drawing export (PDF / JSON / Mermaid).
What we still need to do in Phase 2–3 to fully enable this
- Every gate/zone/camera/controller entity carries optional position_x, position_y, parent_node_id from day one — render-ready without a schema migration.
- Implement Journey as a directed-graph traversal, not a hard-coded entry-to-exit pair lookup — canvas can expand to multi-zone journeys later without rewriting the engine.
- Capacity Engine supports nested zones (zone within zone, share-of-parent) from the start. Cheap to design in, expensive to retrofit.
- Promote SUDIMA_EXAMPLE + SUDIMA_FLOOR_PLAN from in-code constants to a real SiteLayout entity once schema is locked.
Walking a prospect through a drag-and-drop site canvas — or better, watching the AI build their site live from a one-line description — is the kind of demo moment that closes deals against incumbents. Full scoping (worked Sudima Auckland Airport example, technical approach, open questions on schematic-vs-physical canvas + multi-floor sites) in docs/GATED_SITE_ARCHITECTURE.md §11.
Native mobile apps
FutureFor operators and enforcement officers.
- Officer app: plate scan, session lookup, breach issuance.
- Operator app: live dashboard, manual session creation, refunds on the go.
- Push notifications for high-priority events (failed payments, capacity breaches).
- Built on the same React codebase — published to iOS and Android.
Public tenant-facing docs portal
Future- Curated subset of this document, exposed to tenants in-app.
- Per-tenant visibility controls — show only what's relevant to that operator.
- Versioned release notes so tenants can track what's new.
Parker communications — email + SMS
ShippedTwo first-class channels, country-routed, with a unified template preview.
Parkers can be reached by email, SMS, or both — set as a tenant default and overridable per site. SMS runs on WebSMS (NZ/AU) through a per-tenant, per-country messaging account that mirrors how payment accounts are routed, so funds and messages both follow the site's country automatically.
Shipped
- Four parker messages, both channels — verification code, parking-started confirmation, expiry reminder, and session receipt — delivered by email and/or SMS depending on the site's contact mode.
- Exact-time SMS reminders — scheduled at the precise minute before expiry via the SMS provider's native scheduling — no polling lag.
- Country-routed messaging accounts — per-tenant WebSMS account per country (NZ / AU), with location-level override and an automatic default-by-country fallback.
- Message Templates panel — preview every SMS and email template in the order a parker receives them (numbered 1–4), with tenant branding, SMS segment counts, and a one-click 'send test' to any number or address. Lives in Settings → Message Templates.
- Contact-mode control — email only, SMS only, or both (email primary, mobile optional) — set per tenant and per site.
Coming next
- Editable templates (today they're branded but code-defined — an editor is planned, same as for email).
- Per-tenant dedicated SMS sender IDs (today: shared country shortcode/longcode).
- SMS delivery receipts surfaced against each message.
- Permit-channel SMS (currently sessions only).
- Parker accounts (optional) for saved plates, payment methods and history.
Self-serve tenant onboarding
Future- Guided setup wizard for new operators.
- Self-serve Stripe Connect onboarding.
- Sample content and templates pre-loaded for first-time configuration.
Further explorations
Future- Dynamic pricing based on occupancy or demand.
- Reservations and pre-booking for high-demand sites.
- Loyalty / frequent-parker programs at the tenant level.
- Public API for tenant-built integrations.
- Marketplace listings (Getapark, et al.) driven directly by site data.
Strategic Architecture Layers
The eight layers that turn ParkOS into a realtime mobility infrastructure operating system — Stripe + Tailscale + UniFi + Parking OS + realtime IoT orchestration.
What this platform really is
We are not building a parking app. We are building a realtime mobility infrastructure operating system — with commerce, access control, computer vision, edge orchestration, IoT fleet management, tenant SaaS, physical automation and operational tooling wrapped together.
The shape we're converging on: Stripe + Tailscale + UniFi + Parking OS + realtime IoT orchestration. That combination is extremely modern for parking. Incumbents are Windows-heavy, server-heavy, proprietary, vendor-locked and hardware-centric. Our direction is cloud-native, event-driven, API-first, edge-light, modular, AI-compatible and infrastructure-oriented.
The eight sections below formalise the strategic layers that make that combination work. Most are direct extensions of architecture already in flight — the Rules Engine (§8) is the one new layer being scoped formally for the first time.
1 · Event Bus — the nervous system
Next upPromote events from implicit side-effects to a first-class core model.
Today events exist (SessionEvent audit log, webhooks, scheduled SendGrid emails) but they're scattered across each feature. Formalising a single Core Event Model becomes the spine for analytics, AI, edge sync, debugging, replay, audit and integrations.
Core event vocabulary (initial set)
- PlateDetected — any LPR or manual plate observation. Source-tagged (entry / exit / mobile officer / API).
- JourneyStarted / JourneyClosed — vehicle entered / left a site.
- SessionStarted / SessionExtended / SessionExpired / SessionStopped — paid layer lifecycle.
- PaymentCaptured / PaymentRefunded / PaymentFailed — finance signals.
- GateOpened / GateClosed / GateFault — physical-world actions.
- PresenceLoopActive / SafetyLoopActive — IO state transitions.
- CapacityExceeded / CapacityRecovered — derived from Capacity Engine.
- PermitValidated / WhitelistMatched / BlockoutActive — compliance decisions.
- VehicleSignatureGenerated / VehicleSignatureMatched / VehicleSignatureLowConfidence — Phase 6 integrity.
- DeviceOnline / DeviceOffline / DeviceFirmwareUpdated — fleet signals.
Why now
- Webhooks already need a stable event vocabulary — formalise it once, not per feature.
- Ops AI (layer 2 below) needs replay + anomaly streams.
- Edge → cloud event ingestion is a natural fit — same shape both directions.
- ePRO consumer pattern benefits directly: 'subscribe to PlateDetected at site X' instead of polling.
2 · Digital Site Model — sites as graphs, not forms
In progressThe Visual Site Builder is the UI. The data model behind it is a directed graph per site.
Every site becomes a topology graph: entry lanes → zones (possibly nested) → exit lanes, with gates, cameras, controllers, POS and intercoms attached as typed nodes. The Visual Site Builder (Phase 11a, shipped as super-admin prototype) already renders this. The remaining work is promoting it from in-memory layout state to a persisted SiteLayout entity.
What this enables
- Visual builders + AI builder (already prototyped — natural-language → full layout).
- AI simulation — replay a journey through the graph for debugging or sales demos.
- Capacity modelling — nested zones, share-of-parent rules, surge handling.
- Journey replay — given a plate + site, walk the graph to reconstruct what should have happened.
- Troubleshooting — 'why didn't this exit vend?' becomes a graph traversal with decision tags at each node.
- Install drawing export — same graph, rendered with dimensions for the integrator.
See the Visual Site Builder section above for prototype detail and phased delivery.
3 · Device Abstraction Layer — interfaces first, drivers second
Next upVendor neutrality is a Phase 2 commitment — formalise it in code, not just in docs.
Edge devices today are still described in vendor-specific terms (Advantech WISE, Milesight, Windcave). The architecture doc already commits to vendor-abstracted integration. This section pins the contract down.
Abstract device interfaces
- GateController — open() / close() / status() / health() — implemented by AdvantechWISEDriver, GenericModbusDriver, HTTPRelayDriver.
- LPRCamera — onPlateRead(callback) / snapshot() / health() — implemented by MilesightDriver, HikvisionDriver, PlateRecognizerDriver.
- LoopSensor — onStateChange(callback) — abstracts presence + safety loops across IO controller vendors.
- PaymentTerminal — createPaymentIntent() / capture() / void() / health() — implemented by WindcaveDriver, StripeTerminalDriver.
- Intercom — onCall(callback) / answer() / hangup() / health() — implemented by Akuvox/2N SIP drivers.
- EdgeAgent — register() / heartbeat() / ingestEvents() / executeCommand() — single contract every gateway implements.
Why this matters
- Vendor swaps don't touch the core. Camera vendor changes? New driver, same interface.
- Edge MVP can ship with mock drivers and run a full simulator on a laptop (already planned in §10.8 of the architecture doc).
- AI-assisted driver generation becomes safe — the contract is fixed, only the protocol implementation varies.
- Cloud code never knows what brand of LPR is at a site. It just consumes PlateDetected events from any LPRCamera.
4 · Fleet Management — the platform managing itself
Next upDistributed edge nodes need their own ops surface as soon as we hit 3+ sites.
Pilot Phase 2 runs on manual SSH-over-Tailscale + shell scripts (deliberately — one site, low overhead). The moment we hit 3+ sites, fleet management becomes a real product surface, not a side-task.
Capabilities to build
- Device list view — every edge gateway, IO controller, camera and POS — with last-seen, firmware version, agent version, connectivity.
- Remote updates — GitHub Container Registry + custom controlled updater (~200 LOC). Heavyweight tools (Balena, Mender) re-evaluated at ~10 sites.
- Health dashboards — fed by edgeHeartbeat events. CPU, disk, temp, queued event count, cert expiry.
- Config rollout — site-scoped or tag-scoped config push. Edge picks up via config-sync-service.
- Firmware tracking — matrix of device × firmware version × known-good. Alerts on stragglers.
- Edge replacement workflow — wipe → new one-time token → boot → auto-claim identity from cloud. Field-tech friendly.
- Device lifecycle states — provisioning → active → maintenance → decommissioned. Already modelled on EdgeDevice.
5 · Edge Provisioning — UniFi-style onboarding
Next upPlug it in, it joins the right site, it's ready. No SSH gymnastics.
Goal is the UniFi / Tailscale onboarding experience, but for a parking edge gateway. The cloud-side endpoints (edgeProvision, edgeHeartbeat) are already scoped in the architecture doc.
Onboarding sequence
- 1. New edge device boots with a one-time provisioning token (printed on device or QR sticker).
- 2. Auto-register against the cloud — presents token, receives signed DeviceCredential.
- 3. Pull site assignment + initial config from cloud.
- 4. Join the tailnet with the right tags (tag:edge-gateway, tag:site-<slug>, tag:env-<env>).
- 5. Heartbeat starts. Cloud marks device as 'active'.
- 6. Field tech sees green tick in the Fleet view — ready.
Operational impact
- Hardware install becomes a 30-minute job for a generalist sparky, not a 4-hour job for a senior integrator.
- Device replacement during a fault is a swap, not a recommissioning.
- Site go-live time drops from days to hours once cabling is in place.
- Provisioning token + identity-claim flow doubles as our audit trail for hardware deployment.
6 · Realtime Observability — enterprise-grade operational tooling
Next upWhat ops teams at airports, hospitals and large precincts actually procure on.
Once Phase 3 (Journey + Capacity Engine + Lane Activity Console) lands, the natural next layer is operational observability — the metrics enterprise procurement teams compare vendors on.
Operational metrics to surface
- Lane latency — time from LPR read → vend decision → boom up. Target <800ms.
- LPR confidence degradation — rolling average per camera. Alert when a camera's confidence drops — usually means dirty lens or sun angle issue.
- Device offline duration — MTTR per device class. Differentiates 'reliable' vs 'flaky' hardware.
- Gate cycle times — open-to-close per gate. Anomalies = mechanical fault.
- Queue depth — vehicles waiting at exit lanes. Surge alerts.
- Payment failure rate — per-terminal and aggregate. Stripe Terminal / Windcave health signal.
- Edge sync lag — time from event-at-edge → event-in-cloud. Connectivity health.
- Unmatched-exit reconciliation backlog — ops queue depth. Should trend to zero same-day.
Why this is procurement-grade
- Airports, hospitals and CBD precincts buy on SLAs, not features. These metrics ARE the SLA evidence.
- Same dashboard becomes the operator's daily ops surface and our internal support tool — one mental model.
- Anomaly detection (Layer 2 AI below) consumes these streams natively.
7 · AI Strategy — three distinct layers
In progressAI is not a single thing in ParkOS. It's three layers with different risk profiles and timing.
Layer 1 · Developer AI (in use today)
- AI helps us build the platform — drivers, adapters, simulators, log analysis, docs.
- Build-time only. Never sits in the runtime gate-command path.
- Hard guardrails: deterministic gate commands, human-reviewed PRs, production credentials never leave the cloud.
- Already in flight on the cloud side; baked into the §10 edge software workflow.
Layer 2 · Operational AI — "ParkingOps AI" (next 12 months)
AI helps operators run their estate. Diagnose issues, suggest fixes, identify lane problems, detect anomalies. Consumes the Event Bus + Realtime Observability streams from sections 1 and 6. Surfaces as suggestions in the operator app, not autonomous actions — human-in-the-loop by default.
The questions ParkingOps AI answers
- "Why is exit lane 2 failing?" — correlates GateFault events, LPR confidence, IO state, payment terminal health.
- "Why are read confidences down at site X?" — surfaces per-camera trend, suggests lens clean or sun-angle issue.
- "Which cameras are degrading across my estate?" — fleet-wide drift detection.
- "Why did queue time spike between 8:30–8:45 at site Y?" — correlates capacity, gate cycle times, payment terminal latency.
- "Which edge device has sync lag?" — surfaces lagging EdgeHeartbeat against the fleet baseline.
- "Site Y's permit-zone occupancy has been 100% for 4 days — likely permit-holder mismatch, suggest audit."
This is enterprise operational intelligence — the layer airport, hospital and precinct procurement teams expect from a modern platform.
Layer 3 · Computer Vision AI (Phase 6, gated-site differentiator)
- Vehicle fingerprinting + ReID — the Vehicle Session Integrity layer (already scoped in detail above).
- Direction detection — wrong-way and tailgating detection.
- Movement tracking — internal path reconstruction from multi-camera ReID.
- Occupancy intelligence — per-bay state from aerial cameras.
- Purpose-built CV models with deterministic outputs. NOT language-model agents.
- Inference at the edge (N100 → Jetson Orin Nano → Hailo-8). Cloud stores embeddings + decisions only.
Why the separation matters
- Different risk profiles — Layer 1 is internal, Layer 2 is advisory, Layer 3 is on the critical path.
- Different procurement perception — 'AI surveillance' vs 'intelligent session recovery' (we never conflate them).
- Different timing — Layer 1 now, Layer 2 once Event Bus + Observability land, Layer 3 in the Phase 6 wave.
- Different infra — Layer 1 + 2 are cloud-side LLM calls. Layer 3 is edge CV inference, never an LLM.
8 · Rules Engine — realtime parking orchestration
Next upOnce nested zones, chained journeys, permit groups and capacity rules all interact, we need a formal orchestration graph — not ad-hoc if/else scattered through endpoints.
The decision logic at apiComplianceCheck and the future resolveExitDecision is already non-trivial: blockouts, active sessions, active permits, permit groups, whitelists, nested zone resolution, capacity constraints, validations. As gated sites land and Journey + Capacity engines come online (Phase 3), this becomes a true realtime orchestration layer — and it deserves its own architecture rather than growing as inline conditionals.
Core model
- Triggers — Event Bus events that can fire a rule — PlateDetected, JourneyTransitioned, CapacityThresholdReached, PermitValidated, etc.
- Conditions — Predicates against the current event + site state — 'plate has active permit', 'zone capacity > 90%', 'time within blockout window', 'parker on whitelist'.
- Actions — Deterministic outcomes — open gate, charge tariff, suppress breach, redirect to overflow zone, notify operator, log compliance decision.
- Priorities — Ordered evaluation — blockout > permit > whitelist > paid session > grace > unmatched. The first match wins, with the rest recorded for audit.
- Overrides — Operator-applied or temporary rules — 'free egress for VIP event tonight 6-11pm', layered on top of base ruleset with explicit precedence.
Why it deserves its own layer
- Multiple endpoints share the same decision graph — apiComplianceCheck, resolveExitDecision, checkPlateValidity, future capacity-aware admission rules. One engine, many entry points.
- Audit trail is critical — every decision needs a 'why', not just a 'what'. The rules engine emits a decision trace (which rules fired, which short-circuited, final outcome).
- Operator-configurable rules become possible — 'pause enforcement at this site during cleaning hours' isn't a code change, it's a rule override with a validity window.
- Simulation becomes possible — replay an event against the current ruleset to test changes before deploying.
- AI assist (Layer 2) can suggest rule changes — 'this rule fired 47 times last week with no matching session — likely misconfigured, recommend review.'
Shape of the eventual engine
- IF/THEN orchestration graph — declarative rules stored as data (RuleSet entity per tenant + per-location overlays), not hardcoded in functions.
- Pure functions evaluating { event, site_state, ruleset } → { decision, trace, side_effects[] } — same engine runs cloud-side AND in edge degraded-mode fallback caches.
- Side effects (gate vend, payment, webhook) are dispatched outside the evaluator, so the engine itself stays deterministic + replayable.
- Rule authoring UI in v2 — drag-and-drop rule builder for tenant admins. Until then, super-admin JSON config.
- Reuses Event Bus vocabulary (§1) for triggers and Digital Site Model (§2) for site_state context.
This is the layer that turns ParkOS from a set of features into an orchestration platform. It's the difference between "the system that runs the carpark" and "the system the operator runs the carpark with".
ParkOS — Feature Overview & Roadmap · v1.4 — SMS / multi-channel parker comms · Last updated May 2026
Internal document. Content evolves with each release.