Brainstorm Session 8: Integration Strategy¶
Date: 2026-04-15 Objective: Define build vs integrate for all external systems Depends on: Sessions 1-7
⚠️ KeyPay references superseded — 2026-04-18. §Award Interpretation, §Financial Systems, the hexagonal-adapter example (
KeyPayAdapter), the/webhooks/keypaywebhook endpoint, the STP Phase 2 "Option A: KeyPay STP submission" path, and the IRAP feature-toggle table row for KeyPay all predate the decision to drop KeyPay. Phase 1 now ports the 10–20 active ASG Central v2 Modern Awards into Finnest tables via Strangler Fig; Phase 2 builds a native Elixir engine over the Fair Work Commission Modern Awards Pay Database (MAPD) API. STP Phase 2 direct ATO API (Option B) becomes the only path. Seeadrs/adr-016-F-award-interpretation-native-with-fwc-mapd.mdfor the authoritative direction. The brainstorm body below is preserved unchanged for historical context per BMAD convention.
Techniques Used¶
- Mind Mapping — Map all integration points
- SWOT — Build vs integrate for key decisions
Decision Framework¶
| Question | Answer → Action |
|---|---|
| Core to differentiator? | BUILD |
| Commodity function? | INTEGRATE |
| Regulated/complex? | INTEGRATE (specialists handle compliance) |
| Uncertain future? | ABSTRACT behind port/adapter |
Integration Decisions by Category¶
Award Interpretation¶
INTEGRATE (Phase 1) → BUILD COMMON (Phase 2) - Phase 1: KeyPay API for 120+ Awards (~$5-10/employee/month) - Phase 2: Native engine for top 15 Awards (~80% coverage) - Phase 3: Full native if ROI justifies - Hexagonal: AwardInterpreter behaviour → KeyPayAdapter / NativeEngineAdapter
Job Boards¶
INTEGRATE via API - SEEK, Indeed, LinkedIn, Jora, CareerOne - JobBoardProvider behaviour → adapter per board - IRAP: all disabled (offshore data flow)
Communication Channels¶
BUILD orchestration, INTEGRATE delivery
| Channel | Provider | IRAP |
|---|---|---|
| AWS SES (Sydney) | SES (sovereign) | |
| SMS | MessageBird or Sinch | Australian provider |
| Voice | Twilio | Evaluate sovereignty |
| Business API | Disabled | |
| Push | Firebase FCM | FCM (encrypted payload) |
| In-app | Phoenix PubSub (native) | Native |
CommunicationChannel behaviour → adapter per channel/provider.
Government APIs¶
INTEGRATE all
| API | Purpose | Priority |
|---|---|---|
| VEVO | Right-to-work verification | High |
| National Police Check | Background check | High |
| AGSVA myClearance | Security clearance | Medium (defence) |
| ATO STP Phase 2 | Payroll tax reporting | High |
| State WHS | Incident reporting | Medium |
| NHVR | Fatigue compliance | Medium (logistics) |
Financial Systems¶
INTEGRATE for payroll, BUILD for billing - KeyPay: award interpretation + optional payroll processing - Xero/MYOB: accounting sync (invoices, payments) - Billing engine: NATIVE (core to labour hire business model)
External Services¶
| Service | Decision | Replacement |
|---|---|---|
| Calendly | REPLACE | Native scheduling in Recruit module |
| Typeform | ALREADY REPLACED | Native assessment system |
| SendGrid | REPLACE | AWS SES (sovereign, cheaper) |
| SMSGlobal | EVALUATE | MessageBird or Sinch |
| Firebase Analytics | DROP | Native telemetry |
| Firebase Push | KEEP | FCM (encrypted payload) |
| S3 | KEEP | Document storage, sovereign Sydney |
| Google Maps | KEEP | Geofencing, location display |
Architecture: Hexagonal Port/Adapter Pattern¶
# Every external system behind a behaviour (port)
# Example: Award interpretation
defmodule Finnest.Payroll.AwardInterpreter do
@callback calculate_rates(employee_hours, award_code, classification, date, state)
:: {:ok, rate_calculation} | {:error, reason}
end
# Adapters swap at config time
# config/runtime.exs:
# commercial → KeyPayAdapter
# irap → KeyPayAdapter (KeyPay is Australian)
# phase_2 → HybridAdapter (native first, KeyPay fallback)
# test → MockAdapter
Every port: defined as Elixir behaviour, adapter selected via config, IRAP uses different adapters, tests use mocks.
Webhook Ingestion¶
POST /api/v1/webhooks/:provider → verified → event store → Oban worker
Endpoints:
/webhooks/seek → recruit (applications)
/webhooks/keypay → payroll (rate calculations, STP responses)
/webhooks/twilio → reach (delivery receipts, inbound messages)
/webhooks/stp → payroll (ATO acknowledgements)
/webhooks/vevo → onboard (verification results)
/webhooks/firebase → core (device token updates)
All webhooks: signature verified, logged, async processed (Oban), retryable.
STP Phase 2 Integration¶
Finnest payroll → generate STP event (JSON):
- Gross pay, PAYG tax, super guarantee
- Overtime (itemised), allowances (itemised)
- Bonuses, paid leave (by type)
- Employment basis (FT/PT/casual)
- Income type, labour hire indicator
Submit via:
Option A: KeyPay STP submission (if using KeyPay for payroll)
Option B: Direct ATO API (if native payroll)
Track: submission_id, status, ATO response, corrections
IRAP Integration Restrictions¶
| Integration | Commercial | IRAP | Alternative |
|---|---|---|---|
| Job boards (SEEK, Indeed) | Active | Disabled | Internal recruitment |
| Calendly | Active | Disabled | Native scheduling |
| SendGrid | Active | Disabled | AWS SES Sydney |
| Active | Disabled | SMS + in-app | |
| Google/Apple OAuth | Active | Disabled | Microsoft Entra ID |
| Non-AU webhooks | Active | Disabled | AU-only endpoints |
| Anthropic API | Active | Disabled | AWS Bedrock Sydney |
| KeyPay | Active | Active | Australian company |
| Xero/MYOB | Active | Evaluate | Australian companies |
| VEVO/Police Check | Active | Active | Government APIs |
| AWS SES | Active | Active | Sovereign |
| Google Maps | Active | Evaluate | May need AU proxy |
Key Insights¶
Insight 1: Hexagonal Ports Make Every Integration Swappable¶
Change adapter, not business logic. IRAP = different config. Impact: High | Effort: Low
Insight 2: Award Engine Is the Only Strategic Build-vs-Buy¶
Everything else is clearly integrate. Award interpretation = phased approach. Impact: High | Effort: High (phased)
Insight 3: Orchestration = Build, Delivery = Buy¶
Finnest owns the intelligence (who/what/when). Providers handle the pipe. Impact: Medium | Effort: Low
Insight 4: STP Phase 2 Is Non-Negotiable¶
Mandatory for every Australian employer. Day-one requirement. Impact: High | Effort: Medium
Insight 5: IRAP Restricts ~40% of Integrations¶
Adapter pattern makes this config. Defence needs alternative workflows. Impact: Medium | Effort: Medium
Statistics¶
- Categories: 6 (Awards, Job Boards, Comms, Govt, Financial, External)
- Integrations mapped: 25+
- Key insights: 5
- Techniques applied: 2
Generated by BMAD Method v6 - Creative Intelligence