Nimblesite Clinical Coding Platform

Agentic ICD coding powered by patient encounters, clinical notes, and semantic search

Built on Nimblesite DataProvider — compile-time safe database access, migrations, sync, and query for .NET

---

Caution

Not for production clinical use. This is a reference implementation and technology demonstration. Nimblesite is not responsible for any healthcare decisions, clinical outcomes, or regulatory compliance arising from use of this software. Always validate ICD coding through qualified clinical coders and established healthcare governance processes.

---

What Is This?

A full-stack healthcare platform where patient encounters, observations, and clinical notes flow through FHIR-compliant APIs into an agentic pipeline that determines ICD-10 codes via semantic search and RAG.

The system captures the clinical context needed to support automated coding: structured encounter data, conditions, medications, and free-text notes. The ICD-10 service uses pgvector embeddings to semantically match clinical descriptions to the correct codes — the foundation for an AI-assisted clinical coding workflow.

Clinical Data Pipeline FHIR R5 Patient, Encounter, Condition, MedicationRequest Bidirectional sync between Clinical and Scheduling Structured data for coding context

Agentic ICD Coding Semantic search over 16,000+ ICD-10-AM codes pgvector embeddings for clinical text matching RAG pipeline for code determination from notes ACHI procedure code support

Quick Start

Prerequisites: Docker, .NET 10 SDK, GNU Make

make start-docker

That's it. Starts Postgres, migrates schemas, boots all APIs, and serves the dashboard.

Open http://localhost:5173

Other ways to run

# Force-rebuild containers
make start-docker BUILD=1

# Run APIs locally (faster rebuild cycle, Postgres still in Docker)
make start-local

# Ctrl+C stops everything

Services

Service	Port	Role
Dashboard	localhost:5173	React UI — patient management, sync monitoring, code search
Clinical API	localhost:5080	Patient, Encounter, Condition, MedicationRequest
Scheduling API	localhost:5001	Practitioner, Appointment, Schedule, Slot
ICD-10 API	localhost:5090	ICD-10/ACHI codes, semantic search, RAG coding
Gatekeeper API	localhost:5002	Passkey authentication, RBAC authorization
Postgres	localhost:5432	pgvector-enabled, 4 databases

Architecture

graph TD
    Dashboard["Dashboard<br/><sub>React / TypeScript</sub>"]

    Dashboard --> Gatekeeper["Gatekeeper API<br/><sub>Passkey Auth · RBAC</sub>"]
    Dashboard --> Clinical["Clinical API<br/><sub>Patient · Encounter · Condition</sub>"]
    Dashboard --> Scheduling["Scheduling API<br/><sub>Practitioner · Appointment · Slot</sub>"]
    Dashboard --> ICD10["ICD-10 API<br/><sub>Code Lookup · RAG Search</sub>"]

    Clinical <-->|"bidirectional sync"| Scheduling

    ICD10 --> Embedding["Embedding Service<br/><sub>Semantic Code Matching</sub>"]

    Clinical --> PG[("PostgreSQL<br/><sub>pgvector</sub>")]
    Scheduling --> PG
    ICD10 --> PG
    Gatekeeper --> PG

Loading

Clinical and Scheduling sync data bidirectionally — practitioners flow into Clinical, patients flow into Scheduling. The ICD-10 API provides semantic search over medical codes, forming the backbone of the coding pipeline.

Data Ownership

Domain	Owns	Receives via Sync
Clinical	fhir_Patient, fhir_Encounter, fhir_Condition, fhir_MedicationRequest	sync_Provider
Scheduling	fhir_Practitioner, fhir_Appointment, fhir_Schedule, fhir_Slot	sync_ScheduledPatient
ICD-10	icd10_chapter, icd10_block, icd10_category, icd10_code, achi_block, achi_code	— (read-only reference)

Development

make ci             # full CI: lint + test + build
make test           # run all tests (fails on coverage threshold violations)
make lint           # run all linters
make fmt            # format all code
make build          # compile everything (Release)
make clean          # remove build artifacts
make setup          # restore tools + packages (run once after clone)

Database targets

make db-up          # start Postgres container
make db-down        # stop Postgres container
make db-migrate     # apply schemas to all databases
make db-reset       # wipe and recreate databases from scratch

API Reference

Clinical API — :5080

Method	Endpoint	Description
GET/POST	/fhir/Patient	Patients
GET	/fhir/Patient/_search?q=smith	Search patients
GET/POST	/fhir/Patient/{id}/Encounter	Encounters
GET/POST	/fhir/Patient/{id}/Condition	Conditions
GET/POST	/fhir/Patient/{id}/MedicationRequest	Medications
GET	/sync/changes?fromVersion=0	Sync feed

Scheduling API — :5001

Method	Endpoint	Description
GET/POST	/Practitioner	Practitioners
GET	/Practitioner/_search?specialty=cardiology	Search
GET/POST	/Appointment	Appointments
PATCH	/Appointment/{id}/status	Update status
GET	/sync/changes?fromVersion=0	Sync feed

ICD-10 API — :5090

Method	Endpoint	Description
GET	/api/icd10/chapters	ICD-10 chapters
GET	/api/icd10/chapters/{id}/blocks	Blocks within chapter
GET	/api/icd10/codes/{code}	Code lookup (?format=fhir)
GET	/api/icd10/codes?q={query}&limit=20	Text search
GET	/api/achi/blocks	ACHI procedure blocks
GET	/api/achi/codes?q={query}&limit=20	ACHI text search
POST	/api/search	RAG semantic search

Gatekeeper API — :5002

Method	Endpoint	Description
POST	/auth/register/begin	Start passkey registration
POST	/auth/register/complete	Complete passkey registration
POST	/auth/login/begin	Start passkey login
POST	/auth/login/complete	Complete passkey login
GET	/auth/session	Current session info
GET	/authz/check	Permission check
POST	/authz/evaluate	Bulk permission evaluation

Tech Stack

Layer	Technology
Runtime	.NET 10, ASP.NET Core Minimal API
Database	PostgreSQL + pgvector
Data Access	Nimblesite DataProvider (compile-time safe SQL)
Sync	Nimblesite Sync Framework (bidirectional)
Query	Nimblesite LQL (Lambda Query Language)
Embeddings	MedEmbed via FastAPI
Frontend	TypeScript + React + Vite
Infrastructure	Docker Compose

License

MIT