WiqAIa+ Implementation Plan — Overview

Audience: the WiqAIa+ engineering team (Melissa + cloud engineer + AI engineer + AI sub-agents). Read this first. Everything else in docs/plan/ is detail behind what’s framed here.

Status: Living document. Update it when reality changes.

1. What we’re building

WiqAIa+ is an AI-powered control room platform for buildings in Saudi Arabia. It turns existing IP cameras into a 24/7 intelligent safety layer that:

• Detects fire, smoke, crowd hazards, and other anomalies on every connected camera using a tiered AI pipeline.
• Correlates fire-alarm-panel events with live AI analysis of nearby cameras to suppress false alarms (the highest-value capability — Mecca-area incense / bakhoor smoke triggers fire alarms constantly).
• Presents operators with a spatially-aware view of every connected building through a 3D digital twin.
• Routes verified alerts to the right responders (Civil Defence, building managers, fire-department dispatchers) with evidence packages attached.

The platform is multi-tenant by design. Civil Defence is both an end-customer (national HQ view across all connected buildings) and a regulator-style stakeholder. Building owners (hotels, malls, Hajj accommodations, public buildings) are paying tenants.

2. Why this plan exists

The first paying pilot is Saudi Airlines at the Arafat Hajj 2026 site. The Hajj operational window (~May 25 – June 5) is non-negotiable: pilgrims arrive on a date set by the lunar calendar. The platform must be live and stable before they arrive.

We are building from scratch. The prior Electron prototype at C:/Development/WiqAIa/ informs design but is not the build target — the new platform is cloud-deployed, multi-tenant, production-hardened, and architected to scale to thousands of future tenants. (See docs/civil-defence-innovation-submission/ for the planning artifacts and submission docs that informed this.)

The risk profile is unusually severe: both the GCP/CNTXT cloud terms and the customer contract are described as “cut your head off” if we get it wrong. Liquidated damages, billing surprises, data leaks, and missed deadlines all have outsized consequences. This plan is built around protecting the project from those failure modes first, and chasing features second.

3. Operating principles

These govern every decision. When a tradeoff comes up, walk back to these.

1. Safety-first AI sensitivity. False negatives are unacceptable; false positives are tolerable. Every tier of the AI pipeline is tuned to over-escalate, not under-escalate. Missing a fire is worse than crying wolf.
2. Data sovereignty by design. All customer data — video frames, AI results, incident records, audit logs — stays inside the Kingdom of Saudi Arabia. AI models are self-hosted on GCP Dammam (not Vertex AI). Storage uses customer-managed encryption keys (CMEK) and, where possible, application-layer encryption with keys we hold.
3. Cost discipline is a feature, not an afterthought. Budget caps, billing alerts, and quota guardrails are wired in before any GPU spins up. The plan treats cost guardrails as M01 deliverables, equal in weight to code. (Automated kill switches were considered and deferred at pilot scale — see decisions.)
4. Production-hardened from day 1. Real authentication, real RBAC, real audit logging, real encryption, real Postgres (no SQLite-then-migrate), real testing. We do not ship a prototype and promise to harden later.
5. Plug-and-play abstractions, one production driver per type for the pilot. Every external interface (cameras, fire panels, NVRs, AI models, message brokers) sits behind a clean contract. The pilot ships exactly one driver per slot, but the slot is real. New drivers slot in without code changes elsewhere.
6. Test-as-you-build. Every milestone has explicit verification criteria — concrete observable behavior that proves the milestone is done. No milestone is “complete” until its verification passes.
7. AI-agent-friendly structure. Tight conventions, named modules, typed wire contracts, explicit dependencies. Sub-agents working on different milestones in parallel should not collide. Code that’s easy for a competent human reviewer is easy for an LLM agent.
8. Don’t trust the cloud. GCP/CNTXT’s terms grant them rights over stored data. We encrypt before upload, hold our own keys, and treat the cloud as a hostile transport layer for anything sensitive.
9. Simple at the surface, sophisticated underneath. Operators see one button; behind it, the right thing happens. Engineering complexity exists to make operational simplicity possible, not the other way around.

4. Architecture in one paragraph

A small Go edge supervisor runs as a systemd service on one Linux box per building. It hosts a set of Python edge-app containers (camera manager, Tier-0 motion filter, anomaly autoencoder [CPU, ONNX INT8], fire-panel adapter, store-and-forward queue, local dashboard) and maintains a persistent outbound-only mTLS tunnel to the cloud platform. The cloud — running on GKE in GCP Dammam — hosts the multi-tenant API (Node + NestJS), the dashboard (React + Vite SPA, served as static assets), one AI worker service (Python; the Tier-2 multimodal-LLM on a single always-warm L4 GPU node), and the data layer (Postgres + PostGIS, Redis, Cloud Storage with CMEK, Pub/Sub for event distribution). Camera frames flow through the edge filter + autoencoder; flagged frames escalate to the cloud LLM; verdicts trigger spatial correlation against the digital twin (Three.js scene fed by PostGIS) to identify cameras with line-of-sight to alarm zones; correlated evidence packages drive alerts to operators and to a dedicated fire-department view. (Architecture revised 2026-05-13 from a 3-tier to a 2-tier pipeline; see docs/plan/01-architecture-summary.md §0.)

See docs/plan/01-architecture-summary.md for the locked-in tech stack and rationale, and docs/architecture/ for ADRs as they’re written.

5. Locked-in tech stack (summary)

Full table and rationale in docs/plan/01-architecture-summary.md. The short version:

6. Guardrails — the things that protect us

Two non-negotiable guardrails. Both are M01 deliverables, before any application code ships:

• Cost guardrails. GCP billing budget caps with alert thresholds at 25/50/75/90/100/110/120%, hard quota caps on critical SKUs (GPU, vCPUs, disks, logging ingestion), daily anomaly-spike detection. Cost estimates accompany every infrastructure change. See docs/plan/02-cost-guardrails.
• Data protection. Encryption-before-upload for sensitive blobs, CMEK on every GCS bucket and Cloud SQL instance, mTLS on every internal connection, tamper-evident audit log with hash chaining, RBAC enforced at both API and database layers. Plan assumes NCA Critical/Sensitive System classification (to be confirmed) and is built to satisfy NCA ECC + CCC controls. See docs/plan/03-data-protection.md.

These docs are not optional reading for anyone touching infrastructure.

7. Plug-and-play abstractions

The pilot ships one driver per type. The architecture supports more without code changes. See docs/plan/04-abstractions-and-contracts.md.

The packages/contracts/ package (protobuf + JSON Schema) is the canonical home for these interfaces. Drivers depend on the contracts package; consumers depend on the contracts package; drivers and consumers never depend on each other.

8. Parallel tracks

The work parallelizes across roughly six tracks. Any milestone is assignable to one or more tracks; the dependency graph below tells you what can run concurrently.

Sub-agents can be assigned within any track. Cross-track work goes through the packages/contracts/ package — change a contract, and both sides of the wire follow.

9. Milestone roadmap

Milestones, not days. Each milestone defines what it delivers, how we verify it, and which tracks it occupies. Details live in docs/plan/M01-foundations.md through M10-hardening-and-uat.md.

10. Dependency graph

M01 ──┬──> M02 ──> M07 ──> M08 ──> M10
      ├──> M03 ──> M07
      ├──> M04 ──> M05 ──> M06 ──> M07
      └──> M09 ──────────────────────> M10

After M01, M02 / M03 / M04 / M09 can run in parallel. M07 is the integration point; M08 polishes the user-facing surface; M10 closes everything out.

11. Contingencies

We plan for things to go wrong. Three concrete contingencies are wired into the plan from M01, not added when something breaks:

• Dammam GPU shortage. If CNTXT/GCP cannot provision a GPU node in Dammam by the time M06 starts, the Tier-2 LLM worker can deploy to a small on-prem GPU box (Lambda-class workstation or NUC + L4 / 4060-class card, ~$6–15K USD hardware) installed at the customer site, managed by the same edge supervisor. The Tier-2 worker is built with this deployment mode as a first-class option from M01, selected by config — not a last-minute reroute. Same code, different topology. (The edge-side Tier-0 + autoencoder is already on the customer site in both modes.) Detail in docs/plan/05-contingencies.md.
• LLM model swap. Gemma 4 is the target. If it’s not multimodal-capable on release or quality fails our test suite, the LLM-provider interface swaps to Gemma 3 or Qwen 2.5-VL (Apache 2.0, fully permissive) via a single config flag. Test suite includes a fixed set of ~20 evaluation scenarios that every model must pass before promotion.
• CNTXT account delay. If the GCP Dammam account isn’t live by the time we need it, M01 can be completed against a temporary GCP project in another region for dev/staging — never for real customer data. Production deployment is gated on the Dammam account being active; we don’t ship to it before then.

12. Open external dependencies

Resurfaced from Planning/Decisions & Context Log.md and our running reminders. These don’t block the plan but they shape specific milestones — chase them in parallel:

• Fire-panel make/model at the Saudi Airlines Arafat building. Affects M07 driver implementation. Saudi Airlines knows; we don’t yet.
• NVR vendor/model + whether we get access. Affects M04 — camera-direct vs. NVR-routed.
• 3D model file format from the modeler. Affects M07. Assume same as Clock Tower; confirm before delivery so we can request a different format if needed.
• CNTXT / GCP Dammam account activation timeline. Affects M01 critical path. Workaround if delayed: dev/staging in a temporary GCP project.
• Formal NCA classification of the system. Treat as Critical/Sensitive while planning; confirm before any production audit.
• LOA reconciliation. The Letter of Award currently in draft (Al Baddad ↔ Beam Wave) describes a scope materially broader than the actual plan (elevators / access control / PA / firefighting telemetry, on-prem GPU cluster, 100 TB storage server, etc.). Must be revised before either party signs or Beam Wave is contractually bound to deliver something different from what we’re building, with liquidated damages at 0.5%/day. Melissa is aware and chasing.

13. How to use this plan

• Read 00-overview.md (this file) first.
• Then 01-architecture-summary.md for the tech stack rationale.
• Then 02-cost-guardrails.md and 03-data-protection.md before touching any infrastructure. Non-optional.
• Then 04-abstractions-and-contracts.md to understand the interface boundaries.
• Then 05-contingencies.md for the on-prem-GPU / LLM-swap / CNTXT-delay fallbacks (these shape M01 + M05 + M06 decisions).
• Then the milestone files (M01-… through M10-…) for the work itself. Each milestone file follows a consistent template: Goal · Tracks · Deliverables · Verification · Risks · Open questions.
• Operational details (deployment runbooks, incident response, recovery procedures) live in docs/runbooks/ as they’re written, not in the plan.

This plan is a working document. If you find something out of date, fix it in place rather than working around it.