Specifikacija arhitekture Faurenisa
Faurenis je klinički radni prostor za stomatološke ordinacije. Bilježi posjet glasom, izrađuje nacrte zapisa uz nadzirani AI i ništa ne upisuje u karton pacijenta dok to kliničar ne pregleda. Izgrađen je kao jedan modularni monolit na Google Cloudu u EU-u, s izolacijom klinika provedenom u samom PostgreSQL-u te flotom hostanih i vlastitih modela iza jednog sloja usmjeravanja i zaštita. Ovaj dokument opisuje kako sustav radi, modul po modul, i za svaku navedenu mogućnost navodi njezin status.
Tehnička specifikacija vodi se na engleskom jeziku; naslovi i sažeci poglavlja prevedeni su na hrvatski.
System at a glance
- HTTP routes
- 700+
- plus 8 SSE streams and 4 WebSocket paths, every one in a generated route manifest
- Relational tables
- 220+
- clinical plane, plus 20+ in a physically separate research database
- Forward-only migrations
- 300+
- expand → migrate → verify → contract, never generated down-SQL
- Test files
- 3,300+
- plus 18 end-to-end browser specs
- CI ratchets
- 40+
- one-way lints that block a regression from merging
- Architecture decisions
- 32
- 28 accepted, 4 proposed — each one cited where it binds
- QMS hazards tracked
- 129
- 126 requirements, 121 mitigations, 52 verifications
- Interface strings
- 17,000+
- English and Croatian, with key parity enforced in CI
What the platform is
A dental visit produces speech, measurements, images and documents. Faurenis turns those into a structured clinical record without asking the clinician to type. It has three jobs, and the architecture is organised around them:
- Capture. One microphone shared by the whole app: ambient and dictated notes (Scribe), hands-free periodontal charting (Perio), spoken commands and a speech-to-speech assistant (Voice OS).
- Reason. A clinical assistant (Copilot) that answers from the patient chart and from retrieved, cited literature, and a deterministic layer for everything that has a published algorithm.
- Commit. A governed artifact lifecycle: every AI output is a draft with recorded provenance, and only a clinician action moves it into the patient record.
The architecture in one diagram
- Voice OSone microphone
- Scribenotes · dictation
- Periovoice charting
- Documents · Imagingingest
- Model routertiers · fallback · worker
- Copilotclinical · concierge
- Evidence baseretrieve · rank · entail
- Deterministic enginesperio · plan rules
- Encounter spineone visit, one parent
- Artifact lifecycledraft → review → lock
- Clinical factsprojections · timeline
- Audit chain · provenancehash-chained, append-only
Connections (10)
- Voice OS → Scribe
- Scribe → Copilot
- Perio → Deterministic engines
- Copilot → Evidence base
- Model router → Copilot
- Copilot → Artifact lifecycle
- Scribe → Encounter spine
- Encounter spine → Artifact lifecycle · binds
- Artifact lifecycle ⇢ Clinical facts · on accept
- Artifact lifecycle ⇢ Audit chain · provenance
Status legend
A specification that does not say what is shipped is a brochure. Every capability in this document carries one of five statuses, and the same five are used everywhere:
- ProductionProductionServing clinical users under the production configuration.
- PilotPilotBuilt and deployed; enabled per clinic or per user through a rollout grant.
- ShadowShadowRuns on real traffic and records its result, but never changes what a clinician sees.
- Rolling outRolling outImplemented, with deployment or training in progress.
- PlannedPlannedNot available to users: specified in an ADR or plan, or implemented behind a switch that is off everywhere.
How to read this document
Each chapter opens with a three-sentence summary written for a reader who will stop there. Everything below it is the engineering specification. Chapters 1–5 describe the system as a whole; the module chapters use one fixed template so they can be compared side by side.
- An investor or board member
- Start with
- This page, then the summary at the top of each chapter
- An engineer joining the team
- Start with
- Design invariants (02), then the clinical spine (05)
- A security or privacy reviewer
- Start with
- System topology (03) and platform runtime (04)
- A clinical or regulatory reviewer
- Start with
- Product and intended purpose (01), then design invariants (02)
| If you are… | Start with |
|---|---|
| An investor or board member | This page, then the summary at the top of each chapter |
| An engineer joining the team | Design invariants (02), then the clinical spine (05) |
| A security or privacy reviewer | System topology (03) and platform runtime (04) |
| A clinical or regulatory reviewer | Product and intended purpose (01), then design invariants (02) |
Poglavlja
- 01Proizvod i namjena
Faurenis pomaže licenciranim doktorima dentalne medicine u dokumentaciji, parodontološkom kartiranju, pretraživanju literature i radu ordinacije. AI izrađuje nacrte, a odluke donosi kliničar; ništa ne ulazi u zapis bez njegove radnje. Svaka AI funkcija ima zapisanu namjenu, ulaze, izlaze i razinu automatizacije, a izgradnja ne prolazi ako nova AI ruta nije registrirana.
- 02Projektne invarijante
Osam pravila određuje svaki arhitektonski kompromis, a svako je provedeno kodom, ograničenjem baze podataka ili CI provjerom, ne dogovorom. Iza njih stoje numerirane kliničke invarijante za artefakte, izolaciju klinika, oporavak, Scribe, Perio, dokaze i glas. Regresija bilo koje od njih zaustavlja promjenu, bez obzira na to što još donosi.
- 03Topologija sustava
Jedna aplikacijska usluga na Cloud Runu — Node.js modularni monolit — poslužuje web-aplikaciju i API, uz Cloud SQL PostgreSQL 16, Cloud Storage i Cloud KMS. Posao koji traži drugačiji hardver ili strogu granicu izolacije izvodi se u malom broju satelitskih usluga: generator dokumenata, predobrada snimki i GPU servisi za inferenciju. Sve radi u odobrenim EU regijama; nema posrednika poruka, nego asinkroni rad nose Postgres outbox tablice koje se prazne po rasporedu.
- 04Izvršno okruženje platforme
Aplikacija je modularni monolit: domene su odvojene granicama modula i lint pravilima, a ne mrežom, pa klinička transakcija ostaje jedna transakcija baze. Svaki zahtjev prolazi fiksni lanac middlewarea, a svaki AI zahtjev dodatno prolazi provjere usklađenosti, privole, budžeta, revizije i izlaza prije poziva modela. HTTP površinu opisuje generirani manifest koji CI provjerava pri svakoj promjeni.
- 05Klinička okosnica
Svaki modul spaja se na istu okosnicu: jedan susret po posjetu, upravljani životni ciklus za sve što AI proizvede, sloj činjenica u koji ulaze samo podaci koje je kliničar potvrdio te revizijski i provenijencijski trag iza svega. Zato je Faurenis jedna aplikacija, a ne skup AI funkcija: pregled, zaključivanje i ispravci rade jednako u svakom modulu. Okosnica ne sadrži AI; ona je deterministička struktura unutar koje AI radi.
- 06Katalog modula
Faurenis čini devetnaest modula u šest domena — bilježenje, rasuđivanje, slika, izrada, rad ordinacije i upravljanje — i svi pišu kroz kliničku okosnicu. Svaki modul opisan je po istom predlošku: namjena, tok, podaci, modeli, zaštite, status uvođenja, sučelja, invarijante i poznata ograničenja.
- 07AI arhitektura
Svaki poziv modela prolazi jedan sloj usmjeravanja: krajnje točke vežu se na razine, razine na modele, a mehanizam ponavljanja spušta se razinu niže umjesto da zakaže. Gemini modeli na Vertex AI-ju u EU-u služe produkciji, vlastiti modeli na GPU-ima uvode se uz njih, a oko svakog poziva stoji višeslojni sustav zaštita.
- 08Životni ciklus modela
Modeli se poboljšavaju iz odluka kliničara: što su zadržali, promijenili ili odbacili. Te se odluke izvoze bez identiteta, koriste za doradu malih modela, vrednuju na zaključanim skupovima i objavljuju samo kao potpisana izdanja koja odobravaju tri uloge, kroz sjenu, pilot i kliničku fazu.
- 09Arhitektura podataka
Jedan relacijski izvor istine — Cloud SQL PostgreSQL 16 — drži klinički sloj, uz objektnu pohranu za snimke i dokumente te fizički odvojenu bazu za istraživanje. Identifikacijski podaci šifriraju se po pacijentu ključevima omotanima ključem klinike u Cloud KMS-u, a brisanje je osmišljeno i za sigurnosne kopije.
- 10Sigurnost i izolacija klinika
Izolaciju klinika provodi sam PostgreSQL: svaka tablica klinike prisilno primjenjuje sigurnost na razini redaka prema identifikatoru klinike postavljenom iz prijavljene sesije, nikad iz zahtjeva. Statičke provjere dokazuju pokrivenost svake tablice, a napadački test između klinika izvodi se u CI-ju pri svakoj promjeni.
- 11Pouzdanost i rad sustava
Svaka produkcijska isporuka ide plavo-zelenim postupkom, a povratak je ponovna isporuka prethodne verzije uz shemu koja se samo proširuje. Oporavak se uvježbava tjedno: vraćanje iz sigurnosne kopije i vježba otpornosti na ispade, sporost, prelazak baze i rušenja.
- 12Kvaliteta i regulatorno inženjerstvo
Sustav kvalitete vodi se u repozitoriju kao strojno provjereni registri zahtjeva, opasnosti, mjera i provjera, povezanih međusobno i s kodom. Regulatorna klasifikacija je pravna odluka koja još nije donesena; platforma je građena kao da vrijedi stroži ishod.
- 13Inženjerski sustav
Kod u produkciju ulazi jednim postupkom, jednakim za ljude i AI suradnike: plan, implementacija s testovima, sigurnosna provjera, neovisni AI pregled koda, CI i jednosmjerni zapori kvalitete. I same provjere se testiraju: provjera koja ne može vidjeti vlastiti neuspjeh smatra se greškom.
- 14Poznata ograničenja i plan razvoja
Ovo poglavlje na jednom mjestu navodi što nije izgrađeno, nije uključeno ili još nema dokaza. Zapisan nedostatak dobiva termin; prešućen ne dobiva.
- ADodatak A — Arhitektonske odluke
Popis svih arhitektonskih odluka sa statusom kako ga svaka odluka navodi. Popis se generira iz mape `docs/adr/`, pa se nova odluka ovdje pojavljuje u istoj promjeni koja je dodaje.
- BDodatak B — Pojmovnik
Pojmovi korišteni u ovoj specifikaciji, s hrvatskim izrazom koji kliničari vide u proizvodu. Riječi statusa slijede rječnik od pet statusa.