Skip to content

3. System Context (C4 Level 1)

The system context diagram shows Finnest as a single black box surrounded by everyone it talks to — humans and external systems. It is the one diagram that anyone, regardless of technical depth, should be able to understand.

Diagram

C4Context
    title System Context — Finnest (C4 Level 1)

    Person(hrAdmin, "HR Administrator", "Daily roster, compliance, payroll work")
    Person(worker, "Worker / Field Staff", "Accept shifts, clock in/out, credentials")
    Person(manager, "Manager", "Approvals, dispatch, dashboards")
    Person_Ext(client, "Client", "Approves workers, confirms timesheets")
    Person_Ext(auditor, "Auditor", "IRAP / Fair Work — read-only audit")
    Person_Ext(regulator, "Regulator", "Fair Work, WHS — receives extracts")

    System(finnest, "Finnest", "AI-native workforce-management platform. 21 OTP apps in one Elixir release. Dual deployment: commercial + IRAP.")

    SystemDb_Ext(postgres, "PostgreSQL 17", "Single cluster. Relational + JSONB + events + pub/sub + cache + search")
    System_Ext(bedrock, "AWS Bedrock (Sydney)", "AI provider — IRAP")
    System_Ext(anthropic, "Anthropic Direct", "AI provider — commercial")
    System_Ext(fwcMapd, "FWC MAPD", "Modern Award Pay Database")
    System_Ext(smsGlobal, "SMSGlobal", "SMS — MFA + alerts")
    System_Ext(emailProvider, "Email Provider", "Transactional email")
    System_Ext(asgCentral, "ASG Central v2", "Legacy Laravel — read-only bridge")
    System_Ext(accounting, "Accounting Systems", "Xero / MYOB / QuickBooks")
    System_Ext(govIdentity, "Gov Identity Services", "Document + licence verification")

    Rel(hrAdmin, finnest, "Manages roster, compliance, payroll", "HTTPS / LiveView")
    Rel(worker, finnest, "Shifts, clock, credentials", "Flutter + LiveView")
    Rel(manager, finnest, "Approves, dispatches, reads", "HTTPS / LiveView")
    Rel(client, finnest, "Approves workers, confirms", "HTTPS / LiveView")
    Rel(auditor, finnest, "Reads immutable audit", "HTTPS")
    Rel(regulator, finnest, "Receives extracts", "Scheduled")

    Rel(finnest, postgres, "Relational + events", "Ecto")
    Rel(finnest, bedrock, "AI invoke (IRAP)", "HTTPS / Bedrock")
    Rel(finnest, anthropic, "AI invoke (commercial)", "HTTPS")
    Rel(finnest, fwcMapd, "Award data", "HTTPS")
    Rel(finnest, smsGlobal, "SMS", "HTTPS")
    Rel(finnest, emailProvider, "Email", "SMTP / HTTPS")
    Rel(finnest, asgCentral, "Legacy reads (Strangler Fig)", "MyXQL read-only")
    Rel(finnest, accounting, "Payroll export, invoice sync", "HTTPS")
    Rel(finnest, govIdentity, "Verify identity docs", "HTTPS")

    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="2")

Interactive version

For click-through drill-down from this context view into Level 2 containers, dependencies, and decision records, use the interactive C4 browser → published as part of this docs site.

For local editing with live reload (Structurizr Lite): docker compose up structurizr → http://localhost:8080.

Humans who use Finnest

Persona What they do
HR Administrator Daily work surface — roster, compliance checks, onboarding, payroll prep. Power user.
Worker / Field Staff Mobile-first. Accept shifts, clock in/out, update credentials, lodge leave.
Manager Approves leave, dispatches jobs, reads dashboards.
Client (labour-hire / services) Approves workers, confirms timesheets, receives compliance evidence.
Auditor (IRAP / Fair Work) Read-only access to immutable audit trail and compliance attestations.
Regulator (Fair Work, WHS) Receives automated data extracts.

External systems Finnest talks to

System Purpose Binding ADR
PostgreSQL 17 Primary database — relational, JSONB, event store, pub/sub, cache. Single cluster. ADR-002-F
AWS Bedrock (Sydney) AI provider for IRAP OFFICIAL:Sensitive deployment. ADR-003-F, ADR-007-F
Anthropic Direct AI provider for commercial deployment. ADR-0010
Fair Work Commission MAPD Modern award pay database — award interpretation source of truth. ADR-016-F
SMSGlobal SMS notifications (MFA, shift alerts).
Email provider Transactional email. ADR-006-F
ASG Central v2 (MySQL) Legacy Laravel system; read-only bridge during Strangler-Fig migration. ADR-010-F
Xero / MYOB / QuickBooks Accounting integration (hexagonal port, exactly one adapter at GA). ADR-006-F
Government identity services Document verification (licences, credentials). ADR-006-F

Things Finnest intentionally does not do

These are out-of-scope for Finnest and handled by external systems:

  • Payroll execution (bank transfers, tax filing) — Finnest produces the ABA file and exports to accounting systems; the accounting system handles disbursement.
  • Training-content delivery — Finnest's learn module manages credential lifecycle; actual courseware is consumed from third-party LMS via port.
  • Web-facing recruitment advertising — Finnest manages the funnel once leads arrive; SEEK / Indeed integrations push ads.

Further reading