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
| Surface | Path | Who |
|---|---|---|
| Results desk | / | public |
| Filing library | /#library | public |
| Schedule + file an announcement | /admin | SUPER_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.
Every released document needs a link
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
sendOnceperir:<announcementId>:<subscriberToken>:<channel>, so a double-click cannot mail the list twice. A secondpublish()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:
| Tab | Label | Why |
|---|---|---|
| Regulation 62 | Not applicable | the clause does not apply to a company with no listed debt |
| everywhere else | No document listed | the 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), registerspublic/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 whatapp/manifest.tsis 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.tsencrypts each message to that one browser (RFC 8291) and signs the request with the VAPID key (RFC 8292), onnode:cryptowith 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
| Key | Where | Default | Meaning |
|---|---|---|---|
API_URL | investors app env | http://localhost:4100 | server-side only; the browser goes through /api/ir/* |
NEXT_PUBLIC_INVESTORS_URL | build arg | https://investors.utl.awx.to | canonical/OG host, inlined at build |
INVESTORS_PUBLIC_URL | ConfigMap | derived from the ingress host | the link the API puts in notifications |
IR_SEED_FILINGS | API env | true | seed the filing library on boot |
IR_SEED_DEMO_ANNOUNCEMENT | API env | false | a demo board meeting; refused outright in production |
REVALIDATE_SECRET | shared Secret | — | the API uses it to refresh the desk on publish; the app checks it |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY | tenant Secret (root .env, passed by infra/helm-deploy.sh) | unset = browser push off | the pair browsers subscribe with; never rotate casually |
VAPID_SUBJECT | API env or Secret | INVESTORS_PUBLIC_URL | how 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.