Skip to main content

Investor Relations

A listed company's disclosure surface: the results countdown, every filing the company has published, and the desk a company secretary schedules and files an announcement from.

It is a separate app (apps/investors, investors.<domain>) rather than a storefront section. Two reasons, both practical: a listed entity's disclosures should not sit behind shop navigation, and IR deploys on the exchanges' calendar, not the shop's.

Surfaces​

SurfacePathWho
Results desk/public
Filing library/#librarypublic
Schedule + file an announcement/adminSUPER_ADMIN, MANAGER, FINANCE_ADMIN

The announcement state machine​

One record drives the whole public page. Every derived line — countdown, state pill, trading window, intimation deadline — is computed from it, so a date changed in the admin cannot leave a stale sentence somewhere else.

draft ──schedule──▶ scheduled ──T-60min──▶ imminent ──T-0──▶ in_progress ──publish──▶ published
(invisible) (countdown) (board is sitting) (filed)

phaseOf(announcement, now) in investors.service.ts is a pure function of those fields and the clock, and the browser runs the same logic (lib/when.ts) so the countdown can cross zero without waiting for a refetch.

Zero on the clock is the start of the board meeting, not the announcement. A results countdown that hits zero and stops is the classic mistake here: the board meets first, then results are filed. Only a real declaration — declaredAt, stamped by publish() — moves the page to published.

The filing desk loads its own record​

The admin page is force-dynamic and the form fetches the announcement itself, authenticated, from the admin list. It used to be server-rendered with whatever the public endpoint had cached, which meant the form could open holding a stale record and Publish would then file that one instead of the announcement on screen. A UI journey test caught it; the API tests could not, because none of them ever loaded the form and pressed the button.

The form opens the newest record that is not yet published — a published announcement is history, and the next one starts blank.

A document row is a display name, a type and a link to the file on the company's own server; the grey line under the link is that file's real name, read off the URL rather than typed twice. There is no upload yet: the company already hosts its PDFs, and this points at them.

Filing is refused — in the form and in the API — when any document has no link. An announcement whose documents lead nowhere is not a filing.

Fair disclosure​

Nothing may reach a subscriber before it reaches the exchanges.

  • The list of documents is public before publication (an investor may know what is coming); the URLs are withheld until phase === 'published', so a scraper cannot front-run the announcement.
  • publish() flips the record first, then fans out. If notification fails, the filing still stands.
  • The fan-out is sendOnce per ir:<announcementId>:<subscriberToken>:<channel>, so a double-click cannot mail the list twice. A second publish() matches no record (status: { $ne: 'published' }) and notifies nobody.

Trading window​

Shut from the end of the reporting period until 48 hours after declaration, under the PIT code. Both ends are derived — periodEnd(financialYear, period) and declaredAt + 48h — so neither is typed by hand.

Before the period ends the window is open. Saying otherwise on a compliance page is a false restriction, and the first cut of this did exactly that.

Until Publish stamps the real declaration, the reopen date assumes declaration 98 minutes after the meeting opens (ASSUMED_DECLARATION_DELAY). It is recomputed the moment Publish is pressed.

The headline is composed, not typed​

composeHeadline() builds it from type + financial year + period, so "Q2 FY 2026-27" cannot become "Q2 FY27" three months later, and next year's quarters need no code change. It stays editable — the odd announcement never fits a formula — and headlineEdited records that a human took it over.

Regulation 29's five clear days' notice is likewise derived from the board date rather than entered.

The filing library​

211 documents across 253 listings, in seven tabs matching the company's own IR pages, plus an investor-contact tab. Seeded on boot from apps/api/src/investors/data/ir-filings.json and idempotent by the {tenant, tab, section, title, url} unique index — run it twice and the second run reports +0 new.

The URL belongs in that key: the Company Reports page carries six titles twice, four of them pointing at genuinely different documents (a DRHP-era copy and its RHP reissue). Key on the title alone and four filings vanish on every seed. Those four carry a variant — the company's own folder name — because it is the only fact that tells them apart.

Rows with no file:

TabLabelWhy
Regulation 62Not applicablethe clause does not apply to a company with no listed debt
everywhere elseNo document listedthe source page simply carries no file against that row

Dates come from the title where the source has one, then the WordPress upload month (shown italic — month-accurate only), then the coverage period derived from the path. 44 rows carry a quarter with no year because the company files them outside its dated folders; the row says so on hover rather than guessing.

Nothing is copied: every link opens the file on the company's own server.

The desk refreshes the moment something is filed​

The public page is ISR. On its own that means up to the revalidate window of a shareholder reading "Scheduled" for results already with the exchanges — so publish() (and scheduling) POST to the app's /api/revalidate with the shared REVALIDATE_SECRET, the same contract the storefront uses. Measured in the journey test: the desk reflects both a schedule and a filing in under a second.

The call never throws. A missed cache purge must not roll back a filing that has already gone out, and the timed revalidation still catches up.

Notifications​

Email, WhatsApp and browser push, through the existing NotificationService. Subscribers are their own collection (ir_subscribers) — an investor is not a newsletter reader, and mixing the two turns a results filing into marketing.

A ticked channel with nothing to deliver to is dropped at subscribe time. That is not hypothetical: until browser push was wired, ticking "Browser" stored a push channel with no subscription behind it, and those investors got nothing.

Browser push​

  • Subscribing. The server render fetches the VAPID public key (GET /api/investors/push-key), and the Browser option appears only when one is configured. On Notify me the form asks for notification permission inside the click (browsers show the prompt only then), registers public/sw.js, subscribes with that key and posts the subscription with the rest of the form. An iPhone or iPad gets push only once the page is on the Home Screen, which is what app/manifest.ts is for; the form says so.
  • Storing. The API accepts a subscription only from a known push service (Google, Mozilla, Apple, Microsoft) with a valid P-256 key and a 16-byte auth secret. It POSTs to that endpoint later from inside the cluster, so an arbitrary URL would let anyone make the API call internal services; sends also refuse redirects. A push-only sign-up is keyed by its endpoint, so the same browser signing up twice updates one row.
  • Sending. apps/api/src/notifications/web-push.ts encrypts each message to that one browser (RFC 8291) and signs the request with the VAPID key (RFC 8292), on node:crypto with no dependency; its spec reproduces the RFC's worked example byte for byte. The alert is the headline plus one line, sent at high urgency, and a tap opens the desk. A browser on two rows still gets one alert. When a push service answers 404 or 410 the browser has gone, and the subscriber loses that channel.
  • Audit log. Push rows record only the push service's host. The subscription itself holds keys that decrypt messages to that browser.

Verified end to end against Mozilla's push service, with a script acting as the browser: subscribe through the site, publish, receive and decrypt the alert, then unregister and see the next publish drop the subscriber.

Keep the key pair. Browsers bind each subscription to the public key, so a new pair silently orphans every browser subscriber. Generate it once:

node -e "const e=require('crypto').createECDH('prime256v1');e.generateKeys();console.log('VAPID_PUBLIC_KEY='+e.getPublicKey('base64url'));console.log('VAPID_PRIVATE_KEY='+e.getPrivateKey('base64url'))"

Configuration​

KeyWhereDefaultMeaning
API_URLinvestors app envhttp://localhost:4100server-side only; the browser goes through /api/ir/*
NEXT_PUBLIC_INVESTORS_URLbuild arghttps://investors.utl.awx.tocanonical/OG host, inlined at build
INVESTORS_PUBLIC_URLConfigMapderived from the ingress hostthe link the API puts in notifications
IR_SEED_FILINGSAPI envtrueseed the filing library on boot
IR_SEED_DEMO_ANNOUNCEMENTAPI envfalsea demo board meeting; refused outright in production
REVALIDATE_SECRETshared Secret—the API uses it to refresh the desk on publish; the app checks it
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEYtenant Secret (root .env, passed by infra/helm-deploy.sh)unset = browser push offthe pair browsers subscribe with; never rotate casually
VAPID_SUBJECTAPI env or SecretINVESTORS_PUBLIC_URLhow a push service can reach the sender: mailto: or https:

IR_SEED_DEMO_ANNOUNCEMENT is refused when NODE_ENV=production on purpose: a fabricated board meeting on a listed company's IR page is a false intimation, not a demo.

Browser never talks to the API​

Client components call /api/ir/* on this origin, which forwards to /api/investors/* (Codex #12 — NEXT_PUBLIC_* is inlined at build, and a deployed storefront once shipped with the API pinned to the visitor's own machine). The proxy forwards only an allowlist of paths: a permissive [...path] proxy in front of an authenticated API is an open relay onto every other module, and /api/ir/../auth/login would be one traversal away.

Sign-in posts to /api/ir-login, the single explicit exception, which forwards nothing but the credentials to /api/auth/login.

DNS​

investors.<domain> is a second-level subdomain. Cloudflare Universal SSL covers one level only (Codex #18), so grey-cloud the record and let cert-manager issue at origin — the chart already adds the host to the certificate's SANs.