AI-powered clinical NLP platform for extracting structured intelligence from unstructured medical text.
ClinIQ is a full-stack healthcare AI portfolio project built to demonstrate production-minded engineering around clinical natural language processing. It combines a FastAPI backend, a React frontend, a Python SDK, ML-oriented pipeline modules, observability, deployment assets, and security-aware documentation in a single public repository.
- End-to-end product shape: API, UI, SDK, docs, infra, and tests live in one coherent codebase.
- Broad clinical NLP coverage: entity extraction, ICD coding, summarization, risk scoring, de-identification, search, temporal reasoning, and more.
- Production-minded design: auth, rate limiting, monitoring, async workers, Docker, Kubernetes, and deployment guides.
- Public-repo discipline: explicit rules for secrets, PHI safety, and documentation quality.
- Portfolio-ready depth: architecture notes, model cards, tests, and structured contributor guidance.
ClinIQ exposes 31 API endpoint groups across the clinical NLP workflow.
| Area | Capabilities |
|---|---|
| Core analysis | full pipeline orchestration, streaming analysis, enhanced multi-module analysis |
| Extraction | NER, medications, allergies, vitals, sections, abbreviations, assertions, temporal extraction |
| Clinical intelligence | ICD-10 prediction, concept normalization, relation extraction, quality scoring, SDoH, comorbidity |
| Safety and privacy | PHI de-identification, audit-aware architecture, public-repo secret restrictions |
| Search and workflow | hybrid search, batch processing, conversation memory, model management |
| Platform | JWT auth, API keys, Redis caching, Celery workers, Prometheus, Grafana |
Clients Gateway Application Data + Ops
------- ------- ----------- ----------
React SPA ---> Nginx / Ingress ---> FastAPI + Celery ---> PostgreSQL
Python SDK TLS + rate limit ML pipeline modules Redis
REST / cURL auth boundary API schemas + services MinIO / MLflow
Prometheus + Grafana
More detail: Architecture
- Backend: FastAPI, Python 3.11+, Pydantic v2, SQLAlchemy 2, Celery
- Frontend: React 18, TypeScript, Vite, TanStack Query
- ML: PyTorch, HuggingFace Transformers, scikit-learn, scispaCy
- Data and infra: PostgreSQL, Redis, MinIO, MLflow, Docker Compose, Kubernetes
- Quality: pytest, Vitest, Ruff, mypy, Bandit, Trivy, GitHub Actions
- Conda
- Python 3.11+
- Node.js 20+
- Docker + Docker Compose v2+
Use the Conda environment named dev for all Python commands in this repository.
conda activate dev
cp backend/.env.example backend/.env
docker compose up -d postgres redis minio
cd backend
pip install -e ".[dev]"
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000Frontend in a second terminal:
cd frontend
npm install
npm run devUseful local URLs:
- API docs:
http://localhost:8000/docs - Frontend:
http://localhost:5173
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/analyze |
Full pipeline analysis |
POST |
/api/v1/analyze/stream |
Server-sent event streaming pipeline |
POST |
/api/v1/ner |
Named entity recognition |
POST |
/api/v1/icd-predict |
ICD-10 code prediction |
POST |
/api/v1/summarize |
Clinical summarization |
POST |
/api/v1/risk-score |
Risk scoring |
POST |
/api/v1/deidentify |
PHI de-identification |
POST |
/api/v1/search |
Hybrid clinical search |
GET |
/api/v1/health |
Health and readiness checks |
Full reference: API Reference
ClinIQ/
|-- backend/ FastAPI app, ML modules, middleware, DB, tests
|-- frontend/ React application and UI tests
|-- sdk/ Python client SDK
|-- docs/ Architecture, deployment, security, API, model cards
|-- infra/ Kubernetes, Nginx, Prometheus, Grafana
|-- scripts/ Utility scripts
|-- AGENTS.md Repo operating rules for contributors and AI agents