# goshiva/rcm-x architecture

> Architecture diagram of the GitHub repository goshiva/rcm-x, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/goshiva/rcm-x
- Repository: https://github.com/goshiva/rcm-x

## Overview

This is an HCC medical-coding and insurance risk-adjustment platform, with both a document-analysis API/CLI and an authenticated, role-based chart-coding workflow. Its principal workflow extracts medical evidence from PDFs, proposes and maps diagnosis codes to HCCs, calculates RAF and premiums, and produces reports and audit records. The chart workflow adds L1 coding, L2 audit, and audited-record reporting. README capabilities are included where implementation excerpts were unavailable; those links are omitted rather than inferred.

Main entry points: [`app.py`](https://github.com/goshiva/rcm-x/blob/main/app.py) (Analysis API), [`main.py`](https://github.com/goshiva/rcm-x/blob/main/main.py) (Batch CLI), [`backend/app/services/nlp_service.py`](https://github.com/goshiva/rcm-x/blob/main/backend/app/services/nlp_service.py) (Medical NLP), [`backend/app/workers/nlp_worker.py`](https://github.com/goshiva/rcm-x/blob/main/backend/app/workers/nlp_worker.py) (Chart NLP worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_browser["Web client<br/>[app.js]"]
  node_cli["Batch CLI<br/>[main.py]"]
  node_web_api["Analysis API<br/>[app.py]"]
end

subgraph group_analysis["Clinical analysis"]
  node_nlp_service["Medical NLP<br/>[nlp_service.py]"]
  node_ocr["PDF extraction<br/>[ocr_module.py]"]
  node_entity_nlp["Entity identification"]
  node_ml["HCC prediction<br/>[ml_model.py]"]
  node_icd["ICD mapping<br/>[icd_mapper.py]"]
  node_hcc["HCC hierarchy<br/>[hcc_engine.py]"]
  node_risk["RAF calculation<br/>[risk_adjustment.py]"]
  node_reports["Risk reports"]
end

subgraph group_workflow["Chart operations"]
  node_chart_api["Chart API<br/>[chart_routes.py]"]
  node_dashboard["Workflow dashboard"]
  node_chart_assignment["Chart assignment"]
  node_nlp_worker["Chart NLP worker<br/>[nlp_worker.py]"]
  node_cms["CMS model import<br/>[cms_routes.py]"]
end

subgraph group_platform["Identity and records"]
  node_auth_api["Authentication API<br/>[auth_routes.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_risk_service["Risk submissions"]
  node_audit_service["Audit logging<br/>[audit_service.py]"]
  node_chart_store[("Chart records")]
  node_risk_store[("Risk input store")]
  node_user_store[("User records<br/>[user_repository.py]")]
end

node_coder(("Coding professionals"))

node_coder -->|"uses"| node_browser
node_coder -->|"runs"| node_cli
node_browser -->|"requests"| node_web_api
node_cli -->|"extracts"| node_ocr
node_cli -->|"analyzes"| node_entity_nlp
node_cli -->|"predicts"| node_ml
node_cli -->|"calculates"| node_risk
node_cli -->|"generates"| node_reports
node_web_api -->|"extracts"| node_ocr
node_web_api -->|"analyzes"| node_entity_nlp
node_web_api -->|"predicts"| node_ml
node_web_api -->|"validates"| node_icd
node_web_api -->|"calculates"| node_risk
node_web_api -->|"generates"| node_reports
node_chart_api -->|"assigns"| node_chart_assignment
node_chart_api -->|"reads/writes"| node_chart_store
node_chart_api -->|"enqueues"| node_nlp_worker
node_nlp_worker -->|"updates"| node_chart_store
node_nlp_worker -->|"extracts"| node_nlp_service
node_nlp_worker -->|"saves submission"| node_risk_service
node_nlp_worker -->|"records event"| node_audit_service
node_dashboard -->|"submits coding"| node_chart_assignment
node_dashboard -->|"saves submission"| node_risk_service
node_dashboard -->|"records event"| node_audit_service
node_auth_api -->|"authenticates"| node_auth_service
node_auth_service -->|"reads/writes"| node_user_store
node_risk_service -->|"persists"| node_risk_store
node_cms -->|"provides model data"| node_risk_service
node_nlp_service -->|"extracts"| node_ocr
node_nlp_service -->|"identifies entities"| node_entity_nlp
node_nlp_service -->|"maps codes"| node_icd
node_nlp_service -->|"suggests HCCs"| node_hcc
node_nlp_service -->|"predicts codes"| node_ml
node_web_api -->|"serves reference"| node_hcc
node_web_api -->|"searches reference"| node_icd

click node_browser "https://github.com/goshiva/rcm-x/blob/main/static/app.js"
click node_cli "https://github.com/goshiva/rcm-x/blob/main/main.py"
click node_web_api "https://github.com/goshiva/rcm-x/blob/main/app.py"
click node_chart_api "https://github.com/goshiva/rcm-x/blob/main/backend/app/api/charts/chart_routes.py"
click node_dashboard "https://github.com/goshiva/rcm-x/blob/main/backend/app/api/dashboard/dashboard_routes.py"
click node_auth_api "https://github.com/goshiva/rcm-x/blob/main/backend/app/api/auth/auth_routes.py"
click node_auth_service "https://github.com/goshiva/rcm-x/blob/main/backend/app/services/auth_service.py"
click node_chart_assignment "https://github.com/goshiva/rcm-x/blob/main/backend/app/services/chart_assignment_service.py"
click node_nlp_worker "https://github.com/goshiva/rcm-x/blob/main/backend/app/workers/nlp_worker.py"
click node_nlp_service "https://github.com/goshiva/rcm-x/blob/main/backend/app/services/nlp_service.py"
click node_ocr "https://github.com/goshiva/rcm-x/blob/main/src/ocr_module.py"
click node_entity_nlp "https://github.com/goshiva/rcm-x/blob/main/src/nlp_identifier_v3.py"
click node_ml "https://github.com/goshiva/rcm-x/blob/main/src/ml_model.py"
click node_icd "https://github.com/goshiva/rcm-x/blob/main/src/icd_mapper.py"
click node_hcc "https://github.com/goshiva/rcm-x/blob/main/src/hcc_engine.py"
click node_risk "https://github.com/goshiva/rcm-x/blob/main/src/risk_adjustment.py"
click node_reports "https://github.com/goshiva/rcm-x/blob/main/src/report_generator.py"
click node_cms "https://github.com/goshiva/rcm-x/blob/main/backend/app/api/cms/cms_routes.py"
click node_risk_service "https://github.com/goshiva/rcm-x/blob/main/backend/app/services/risk_adjustment_service.py"
click node_audit_service "https://github.com/goshiva/rcm-x/blob/main/backend/app/services/audit_service.py"
click node_chart_store "https://github.com/goshiva/rcm-x/blob/main/backend/app/repositories/chart_repository.py"
click node_risk_store "https://github.com/goshiva/rcm-x/blob/main/backend/app/repositories/risk_adjustment_repository_sqlalchemy.py"
click node_user_store "https://github.com/goshiva/rcm-x/blob/main/backend/app/repositories/user_repository.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_cli,node_web_api toneBlue
class node_nlp_service,node_ocr,node_entity_nlp,node_ml,node_icd,node_hcc,node_risk,node_reports toneAmber
class node_chart_api,node_dashboard,node_chart_assignment,node_nlp_worker,node_cms toneMint
class node_auth_api,node_auth_service,node_risk_service,node_audit_service,node_chart_store,node_risk_store,node_user_store toneRose
class node_coder toneIndigo
```

## Components

### User entry points

- [Web client](https://github.com/goshiva/rcm-x/blob/main/static/app.js): `static/app.js`
- [Batch CLI](https://github.com/goshiva/rcm-x/blob/main/main.py): `main.py`
- [Analysis API](https://github.com/goshiva/rcm-x/blob/main/app.py): `app.py`

### Clinical analysis

- [Medical NLP](https://github.com/goshiva/rcm-x/blob/main/backend/app/services/nlp_service.py): `backend/app/services/nlp_service.py`
- [PDF extraction](https://github.com/goshiva/rcm-x/blob/main/src/ocr_module.py): `src/ocr_module.py`
- [Entity identification](https://github.com/goshiva/rcm-x/blob/main/src/nlp_identifier_v3.py): `src/nlp_identifier_v3.py`
- [HCC prediction](https://github.com/goshiva/rcm-x/blob/main/src/ml_model.py): `src/ml_model.py`
- [ICD mapping](https://github.com/goshiva/rcm-x/blob/main/src/icd_mapper.py): `src/icd_mapper.py`
- [HCC hierarchy](https://github.com/goshiva/rcm-x/blob/main/src/hcc_engine.py): `src/hcc_engine.py`
- [RAF calculation](https://github.com/goshiva/rcm-x/blob/main/src/risk_adjustment.py): `src/risk_adjustment.py`
- [Risk reports](https://github.com/goshiva/rcm-x/blob/main/src/report_generator.py): `src/report_generator.py`

### Chart operations

- [Chart API](https://github.com/goshiva/rcm-x/blob/main/backend/app/api/charts/chart_routes.py): `backend/app/api/charts/chart_routes.py`
- [Workflow dashboard](https://github.com/goshiva/rcm-x/blob/main/backend/app/api/dashboard/dashboard_routes.py): `backend/app/api/dashboard/dashboard_routes.py`
- [Chart assignment](https://github.com/goshiva/rcm-x/blob/main/backend/app/services/chart_assignment_service.py): `backend/app/services/chart_assignment_service.py`
- [Chart NLP worker](https://github.com/goshiva/rcm-x/blob/main/backend/app/workers/nlp_worker.py): `backend/app/workers/nlp_worker.py`
- [CMS model import](https://github.com/goshiva/rcm-x/blob/main/backend/app/api/cms/cms_routes.py): `backend/app/api/cms/cms_routes.py`

### Identity and records

- [Authentication API](https://github.com/goshiva/rcm-x/blob/main/backend/app/api/auth/auth_routes.py): `backend/app/api/auth/auth_routes.py`
- [Authentication service](https://github.com/goshiva/rcm-x/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Risk submissions](https://github.com/goshiva/rcm-x/blob/main/backend/app/services/risk_adjustment_service.py): `backend/app/services/risk_adjustment_service.py`
- [Audit logging](https://github.com/goshiva/rcm-x/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`
- [Chart records](https://github.com/goshiva/rcm-x/blob/main/backend/app/repositories/chart_repository.py): `backend/app/repositories/chart_repository.py`
- [Risk input store](https://github.com/goshiva/rcm-x/blob/main/backend/app/repositories/risk_adjustment_repository_sqlalchemy.py): `backend/app/repositories/risk_adjustment_repository_sqlalchemy.py`
- [User records](https://github.com/goshiva/rcm-x/blob/main/backend/app/repositories/user_repository.py): `backend/app/repositories/user_repository.py`

### Other components

- **Coding professionals**

## Connections

- Coding professionals → Web client: uses
- Coding professionals → Batch CLI: runs
- Web client → Analysis API: requests
- Batch CLI → PDF extraction: extracts
- Batch CLI → Entity identification: analyzes
- Batch CLI → HCC prediction: predicts
- Batch CLI → RAF calculation: calculates
- Batch CLI → Risk reports: generates
- Analysis API → PDF extraction: extracts
- Analysis API → Entity identification: analyzes
- Analysis API → HCC prediction: predicts
- Analysis API → ICD mapping: validates
- Analysis API → RAF calculation: calculates
- Analysis API → Risk reports: generates
- Chart API → Chart assignment: assigns
- Chart API → Chart records: reads/writes
- Chart API → Chart NLP worker: enqueues
- Chart NLP worker → Chart records: updates
- Chart NLP worker → Medical NLP: extracts
- Chart NLP worker → Risk submissions: saves submission
- Chart NLP worker → Audit logging: records event
- Workflow dashboard → Chart assignment: submits coding
- Workflow dashboard → Risk submissions: saves submission
- Workflow dashboard → Audit logging: records event
- Authentication API → Authentication service: authenticates
- Authentication service → User records: reads/writes
- Risk submissions → Risk input store: persists
- CMS model import → Risk submissions: provides model data
- Medical NLP → PDF extraction: extracts
- Medical NLP → Entity identification: identifies entities
- Medical NLP → ICD mapping: maps codes
- Medical NLP → HCC hierarchy: suggests HCCs
- Medical NLP → HCC prediction: predicts codes
- Analysis API → HCC hierarchy: serves reference
- Analysis API → ICD mapping: searches reference