Skip to content
OpesCare Developers
EN FR
Get API keys

Architecture and flows

Platform architecture

Every client, from the website to a partner hospital system, talks to one host: opescare.com. Requests pass an authentication gate and, for anything clinical, a consent gate before they reach a service.

Overview

OpesCare platform architecture Clients connect to opescare.com. Web routes, the REST API and the FHIR R4 endpoint pass authentication, consent and ingest gates before reaching the Health ID, clinical records, finders, documents, payments and webhook services, which store data in PostgreSQL, use queue workers and write an access log. OPESCARE.COM Clients website, app, partners, Bridge Web routes server-rendered pages REST API /api/v1/connect, /api/mobile FHIR R4 ingest /api/fhir/R4 Authentication session, JWT, scopes Consent gate relationship or grant Ingest guard facility, Health ID, grant Refused 401 or 403, nothing read OpesCare services Health ID, records, finders PostgreSQL records, register, ledger Access and audit log who read what, when Response every read logged signed in basis held Person or device OpesCare service Stored data Gate (check) Outcome: done Outcome: refused Request Response Refusal or failure
  1. A client calls opescare.com The website, the app, partner systems and the Bridge Agent reach one of three entry points: web routes, the REST API or the FHIR R4 endpoint.
  2. Authentication Web routes use a session; the API checks a signed JWT and its scopes.
  3. Consent gate A clinician read passes the clinical relationship gate before any service answers.
  4. FHIR ingest guard Partner writes pass the three ingest gates: facility from the token, an existing Health ID, an active grant.
  5. Stored and logged Services read and write PostgreSQL, and every read of a record is written to the access log.
  6. Refused A failed check answers 401 or 403 and nothing is read or written.
How this diagram is verified 21 of 21 checks pass

The picture, the steps, the PDF and the JSON are generated from one specification. An automated test proves the graph and checks every reference below against the running application.

  • Every card has a unique id
  • Every card has a known kind
  • Every arrow joins two existing cards
  • Exactly one starting point (a person, device or partner)
  • Every card is reachable from the start
  • Every card leads to an outcome (no dead ends)
  • No cycles except declared retry loops
  • Every numbered step follows real arrows
  • Outcomes end the flow
  • No two cards share a grid cell
  • Every card names its evidence
  • Every route, class, method and setting exists
  • Every icon is from the Lucide set
  • Every icon fits its card kind
  • Every label exists in English and French
  • Every label fits its card
  • No arrow crosses a card
  • No two unrelated arrows run on top of each other
  • No arrow label covers a card or another label
  • Every arrowhead is visible
  • Connected cards of different kinds never share a colour
CardEvidence in the code
Clients route:docs.index route:docs.widget route:docs.bridge
Web routes route:login route:public.network.medicine-finder
REST API uri:POST api/v1/connect/auth/token uri:GET api/mobile/consents
FHIR R4 ingest uri:POST api/fhir/R4 uri:GET api/fhir/R4/metadata
Authentication route:login.submit method:App\Http\Controllers\Api\V1\Connect\AuthController::introspect
Consent gate method:App\Support\ClinicalRelationshipGate::evaluate config:staff_capabilities.capabilities.clinical_chart
Ingest guard method:App\Services\Fhir\FhirIngestGuard::requireConsent
Refused route:docs.errors
OpesCare services class:App\Modules\PatientIdentity\Services\PatientIdentityService class:App\Services\WebhookService route:public.care-map
PostgreSQL config:database.connections.pgsql
Access and audit log class:App\Models\AccessLog uri:GET api/mobile/access-logs
Response route:docs.api

All flows as JSON

The layers

Clients

The opescare.com website, the OpesCare mobile app, partner systems (hospital, lab and pharmacy software) and the Bridge Agent and Widget.

opescare.com

One Laravel application: web pages, the REST API under /api (Connect v1 and mobile) and the FHIR R4 endpoint under /api/fhir/R4.

Gates

Session and bearer-token authentication with scopes, the clinical relationship gate on every clinician read, and the FHIR ingest guard on every partner write.

Services

Health ID and the master patient index, clinical records, the four finders, documents and verification, one-off payments and webhooks.

Data

PostgreSQL holds the records; queue workers deliver webhooks and imports in the background; every clinical access lands in the access and audit log.

Key flows

Every flow as machine-readable JSON /docs/flows.json

Consent and scoped access A clinician asks, the patient approves in the app, access is scoped and time-limited, every read is logged, and the patient can revoke. FHIR R4 ingest A partner posts a transaction Bundle with a bearer token; three gates check facility, Health ID and consent; the Bundle is stored all-or-nothing. Duplicate detection and reversible merge Scheduled scans propose likely duplicate Health IDs, a person reviews each pair, and a merge keeps a survivor, turns the other into an alias and can be undone. Webhook delivery Events are queued, signed with HMAC-SHA256, sent only to public addresses, retried on failure and can be replayed. Health ID QR verification A verifier scans the patient Health ID QR and opescare.com answers with one of four states; a successful scan is recorded.

Design rules the code enforces

  • Facility identity comes from the authenticated session or signed token, never from a request body, header or query string.
  • A clinician reads a patient record only with a basis: an appointment, care team, treating relationship, facility episode or an active consent grant.
  • Partners may write clinical data for an existing Health ID they hold consent for. They can never create a Health ID.
  • Finder availability comes only from live stock on an allow-list of source systems. An empty result is a correct result.
  • Nothing merges patient identities automatically. Every merge is a human decision and can be undone.