BDC Planning Tracker Setup

Pilot topology, mail import, PA sync paths, and office-side components.

Solid boxes are known from the repo. Dashed boxes are placeholders to confirm.

Users Access

Office PCs and mobile users Open https://pilot.bdc.com.mt through browser/PWA.
Clerk sign-in Allowed users are linked to active tracker organisations.

Google Cloud Pilot Public HTTPS

pilot.bdc.com.mt Custom domain for Cloud Run service bdc-tracker-pilot.
FastAPI backend Serves API, dashboard shell, downloads, health, auth middleware.
Frontend dashboard Applications, Third Party, Import Review, Billing, Admin, PWA service worker.
PostgreSQL database Tracker register, raw imported emails, parsed updates, orgs, workers, sync jobs.

Live health endpoint currently exposes the pilot build version; check this before code changes.

External Services Internet

Clerk User sign-in, session tokens, organisation access gate.
Google Gmail OAuth Delegated Mail.Read import for PA correspondence where configured.
Microsoft 365 OAuth Delegated Graph Mail.Read import, callback at /api/email/oauth/callback/microsoft_graph.
Planning Authority / eApps Public case pages; read by browser extension or outbound worker for PA sync.
DNS / edge provider Confirm whether pilot.bdc.com.mt is handled by registrar DNS, Cloudflare, or Google mapping.

Office Side Local / Outbound

BDC-NAS Project root path stored as \\BDC-NAS\bdcNAS\PROJECTS.
Malta Windows worker PC Outbound worker polls pilot for jobs and posts heartbeat/status. No inbound port required.
BDC PA Sync Chrome extension Reads active PA/eApps page HTML and sends it to the signed-in tracker.
Local network / VPN Confirm firewall, Tailscale, VLANs, and whether any Synology Docker services are still active.
control.home.mintoff.app Known domain mentioned separately; auth and hosting details still to map.

Tracker Data Model Source of Truth

Raw imported email records Stored before parsing, including PDF text and attachment metadata.
Planning register Applications, status history, requirements, deadlines, folder paths.
Review queues Uncertain parser results, Import Review, manual PDF upload.
Third Party register Following, Representees, Case Studies, PA sync, Sleep, Starred, Billing.

Primary Flows Operational

Email import flow Gmail or Microsoft 365 -> raw email records -> parser -> Import Review or Planning Register.
PA sync flow Tracker queues/requests PA read -> extension or worker fetches eApps page -> backend validates and updates case data.
Office file flow Tracker stores folder paths and project references; NAS remains local office storage.
Admin flow Platform/admin screens manage org members, modules, email connection, PA sync mode, worker clients.
Cloud Run FastAPI PostgreSQL Clerk Gmail Microsoft Graph PA / eApps BDC-NAS Outbound worker