Penguin Ai - Intelligent HCC Coding and Risk Adjustment

1. Product overview A HIPAA-aware backend service that extracts ICD-10-CM codes from medical charts and computes HCC/RxHCC risk-adjustment scores. It runs OCR over clinical documents with Amazon Textract, applies LLM extraction with Claude models on Amazon Bedrock to produce evidence-backed code suggestions, and supports a coder/auditor review workflow, chart assignment, claims, and reporting.

Key capabilities: ICD-10-CM extraction backed by the 2025 code set, midyear mappings, and coding guidelines; HCC and RxHCC risk scoring over extracted and submitted diagnoses; chart assignment with per-user capacity limits and draft/final states for both coder and auditor roles; change-log auditing of review actions; claims and reporting endpoints; ICD search across the bundled code set; admin configuration for risk-score and workflow settings, roles, and UI features; and a batch processor for bulk chart ingestion.

The service runs entirely on AWS services. It exposes a REST API (OpenAPI/Swagger) and ships as a single container image that serves both the API and the batch processor.

2. Product at a glance Runtime: FastAPI + Uvicorn (Python 3.11), non-root container (user appuser) Listening port: 8000/tcp (HTTP, behind a TLS-terminating ingress) Health endpoint: GET /health returns {"status":"healthy"}. Liveness only - see Section 8. API docs: GET /docs, GET /redoc, GET /openapi.json Route prefixes: /auth, /charts, /claims, /icd_search, /reports, /admin Roles: admin, coder, coder_draft, auditor, auditor_draft State: stateless - all persistent data lives in external, buyer-owned AWS services Volumes: none required - see Section 5 Version: 1.0.1

ROOT_PATH defaults to /hcc-icd, not to root. The same image also serves a Snowflake Native App deployment, which is mounted under that prefix. If your ingress serves the API at its root, set ROOT_PATH="" or every path is prefixed and the UI and probes will 404.

3. Prerequisites Provision the following in your own AWS account and supply their coordinates through environment variables or AWS Secrets Manager:

Amazon EKS or Amazon ECS - the container runtime. Amazon DocumentDB (MongoDB-compatible, TLS) - charts, codes, users, roles, audit records. The CA certificate ships in the image at /app/global-bundle.pem. Use an instance-based 5.0 cluster so the service can authenticate with IAM through its role instead of a stored password (Section 5). Amazon Bedrock with Claude model access enabled in the deployment Region - the inference engine for code extraction. Model access is requested per Region in the Bedrock console; a Region without it returns AccessDeniedException at runtime. Amazon Textract - OCR for clinical PDFs and images. No endpoint or key is configured; access is granted entirely through the container's IAM role (Section 9). Amazon S3 - source documents, generated artifacts, and the reference-data files below. Microsoft Entra ID app registration - OAuth sign-in and role mapping. This is an identity provider only; no PHI is sent to it. Application Load Balancer / Ingress with a TLS certificate forwarding to port 8000. Optional: AWS Secrets Manager for JWT_SECRET and AZURE_SECRET, and Amazon ElastiCache is not used by this product.

Seed the reference data before first start. Upload these five files to data_sources/ in your S3 bucket; the service downloads any that are missing at startup, and coding is degraded without them:

icd10cm_codes_2025.csv 2025 Midyear_Final ICD-10-CM Mappings.csv new_ICD_final.csv ICD_codes_order.json ICD-10-CM-April-2025-Guidelines-for-Coding-and-Reporting.pdf Keep DocumentDB, S3, Bedrock, Textract, and the compute in the same Region so inference and OCR stay in-Region and no cross-Region data transfer occurs.

4. Deployment (high level) Subscribe to the product and pull the container image from Amazon ECR (URI and tag shown on the product's Launch page):

aws ecr get-login-password --region us-east-1 | docker login --username AWS
--password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com//hcc-icd-api:1.0.1 Provision the prerequisites in Section 3, enable Claude model access in Amazon Bedrock for your Region, and upload the five reference-data files to data_sources/ in your bucket.

Create the IAM role. One role serves the API and the batch processor:

bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on the configured model ARN. textract:DetectDocumentText and textract:AnalyzeDocument, plus textract:StartDocumentTextDetection and textract:GetDocumentTextDetection if you process multi-page documents asynchronously. s3:GetObject, s3:PutObject, and s3:ListBucket on the configured bucket. secretsmanager:GetSecretValue and kms:Decrypt if you store secrets in Secrets Manager. DocumentDB needs no IAM permission; access is granted inside the database (Section 5). On Amazon EKS, bind the role with IRSA: associate an OIDC provider with the cluster, then create the role with a trust policy allowing sts:AssumeRoleWithWebIdentity where the provider's :sub condition equals system:serviceaccount::. Annotate the ServiceAccount with eks.amazonaws.com/role-arn=<ROLE_ARN> and set serviceAccountName on the pod spec. A single eksctl create iamserviceaccount command performs all four steps.

On Amazon ECS, pass the role as taskRoleArn. The separate executionRoleArn needs ECR pull and secret-read permissions.

Deploy on Amazon EKS: run the API as a Deployment on container port 8000 behind an Ingress with TLS, using GET /health as the health check path. Do not override the image's command; the default (uvicorn app:app --host 0.0.0.0 --port 8000) starts the API correctly.

Deploy on Amazon ECS: register a Fargate task definition with networkMode: awsvpc, 1 vCPU / 2 GB, a port mapping on container port 8000, awslogs log configuration, and taskRoleArn from step 3. Create a service behind an ALB target group (target type ip, port 8000, health check path /health). The image declares its own container health check against /health.

Set ROOT_PATH="" if the ingress serves the API at its root. The default is /hcc-icd.

Verify (Section 8): confirm /health, open /docs, sign in via GET /auth/ms/login_url, and call a protected endpoint. Then read the startup logs - see the warning in Section 8.

Scale by adding API replicas behind the load balancer. Batch chart processing runs separately as a scheduled task from the same image with the command python -m batch.processor, configured by BATCH_SOURCE_TYPE and BATCH_S3_BUCKET.

5. Configuration (high level) Configuration is environment-variable driven. Store secrets in AWS Secrets Manager or SSM Parameter Store and inject them as environment variables; never bake them into the image.

Application:

ROOT_PATH - mount prefix. Defaults to /hcc-icd; set to "" to serve at the ingress root. CODING_CAPACITY, AUDITING_CAPACITY - per-user chart assignment limits. Backend selection:

DB_TYPE - set to documentdb for an AWS deployment. CLOUD_PROVIDER - set to aws. Database:

MONGO_URI, MONGO_DATABASE - DocumentDB connection. See "Connecting to DocumentDB with IAM" below. Note that MongoDB settings are read at startup regardless of DB_TYPE in order to seed default UI features. On an AWS deployment DB_TYPE=documentdb already supplies them, so no extra configuration is needed. Storage:

AWS_REGION - Region for S3, Textract, and Secrets Manager. AWS_BUCKET_NAME - bucket holding documents, artifacts, and the data_sources/ reference files. Inference (Amazon Bedrock):

BEDROCK_REGION - the Region whose Bedrock endpoint serves inference. Set it to a Region where Claude model access is enabled; keeping it equal to AWS_REGION avoids cross-Region PHI transfer. BEDROCK_MODEL_ID - the Bedrock model identifier. Bedrock model IDs carry an anthropic. prefix, for example anthropic.claude-opus-5. To use cross-Region capacity, supply a cross-Region inference profile instead (identifiers are prefixed by geography, such as us.anthropic.claude-opus-5, and may also be given as a full inference-profile ARN). OCR (Amazon Textract): no configuration keys. OCR runs in AWS_REGION and is authorized entirely by the container's IAM role.

Authentication:

AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_APP_ID, AZURE_SECRET - Microsoft Entra ID app registration. JWT_SECRET - signs the API's own access and refresh tokens. ACCESS_TOKEN_EXPIRE_MINUTES, REFRESH_TOKEN_EXPIRE_MINUTES - token lifetimes. Batch processor: BATCH_SOURCE_TYPE, BATCH_S3_BUCKET.

Connecting to DocumentDB with IAM. Authenticate with IAM authentication through the container's role, so no database password is stored anywhere. The connection is entirely URI-driven and the CA certificate is already in the image, so set MONGO_URI to:

mongodb://:27017/?authMechanism=MONGODB-AWS&authSource=%24external&tls=true&tlsCAFile=/app/global-bundle.pem&retryWrites=false&replicaSet=rs0 Notes on that string:

authSource=%24external - the $ must be URL-encoded, or the driver rejects the URI. retryWrites=false is required by DocumentDB. tlsCAFile=/app/global-bundle.pem points at the CA already shipped in the image. Do not mount over that path. No username or password appears in the URI; credentials are resolved from the container's IAM role by the AWS credential chain. Authorization is granted in the database, not in IAM. No IAM policy grants DocumentDB access. Connect once as the DocumentDB primary user and map the role ARN to a database user:

use $external; db.createUser({ user: "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>", mechanisms: ["MONGODB-AWS"], roles: [ { role: "readWrite", db: "<MONGO_DATABASE>" } ] }); IAM authentication requires an instance-based DocumentDB 5.0 cluster and cannot be used for the cluster's primary user. If your cluster cannot meet that, put a password in MONGO_URI instead and rotate it as described in Section 7.

Ports: 8000/tcp is the only listening port. The batch processor opens no ports.

Volumes: none are required. The container writes to two directories it creates at build time, /app/uploads (transient uploads) and /app/data_sources (reference files downloaded from S3 at startup); both are owned by the non-root user and ephemeral storage is sufficient. Mounting a persistent volume at /app/data_sources is optional and only avoids re-downloading the reference files on every start. Application code and the CA bundle are shipped read-only; do not mount over /app/global-bundle.pem.

6. Data, sensitive information and encryption Where data is stored - the container holds no durable data, and all of it stays inside your own AWS account:

Charts, extracted codes, risk scores, users, roles, and audit records go to Amazon DocumentDB (buyer-owned). Source documents, generated artifacts, and reference data go to Amazon S3 (buyer-owned). Secrets go to AWS Secrets Manager (buyer-owned). Clinical text is sent to Amazon Bedrock for inference and to Amazon Textract for OCR. Both are AWS services, both are HIPAA-eligible, and both are covered by your AWS Business Associate Addendum. No PHI leaves AWS. Amazon Bedrock does not retain your prompts or completions, and does not use them to train models.

Microsoft Entra ID is used for sign-in only. It receives authentication traffic, not PHI.

Encryption:

In transit: TLS everywhere. The ingress terminates HTTPS; DocumentDB connections use TLS with the bundled CA; all AWS SDK calls, including Bedrock and Textract, use HTTPS. At rest: enable AWS KMS encryption on DocumentDB, S3, and Secrets Manager when you provision them. 7. Credentials and rotation Because inference, OCR, storage, and the database all authenticate through the container's IAM role, there are few long-lived secrets. Rotate what remains on your normal cadence (90 days or less):

JWT_SECRET - rotating it invalidates every outstanding access and refresh token and forces all users to sign in again. Plan the rollout accordingly. AZURE_SECRET - the Entra ID client secret. Rotate before expiry and overlap old and new during cutover. DocumentDB credentials - with IAM authentication there is no database password to rotate. If you embedded one in MONGO_URI, use managed rotation and redeploy. Amazon Bedrock and Amazon Textract - no credentials to rotate; access is authorized by the IAM role and the credentials behind it are short-lived and rotated automatically. AWS access: use IRSA on EKS or the task role on ECS. Avoid long-lived access keys. global-bundle.pem in the image is a public certificate authority bundle, not a secret.

8. Backup, recovery and health Backup / recovery:

Amazon DocumentDB (system of record): enable automated snapshots and point-in-time recovery. To recover, restore to a new cluster and repoint MONGO_URI. Amazon S3: enable versioning, and cross-Region replication if you need regional DR. Keep the five data_sources/ reference files in any replacement bucket. For regional DR, confirm Claude model access is enabled in Amazon Bedrock in the failover Region as well; model access is granted per Region and does not follow a restored cluster.

Because the container is stateless, DR is: restore DocumentDB and S3, redeploy the image, repoint the configuration.

Health monitoring:

GET /health returns {"status":"healthy"} and is the correct load balancer and liveness path. Startup is deliberately fault-tolerant, so a passing health check is not proof the service is working. Database, storage, and reference-data errors during startup are logged and the API still starts, so that /docs stays reachable for diagnosis. /health will report healthy even if DocumentDB never connected or the reference files failed to download. Always read the startup logs after deploying and confirm the line Application startup completed successfully; if you instead see Error during startup (app will continue), the deployment is degraded. Confirm running replicas match desired in the EKS or ECS console. Send container logs to CloudWatch Logs. Recommended alarms: container restarts and crash-loops; replicas below desired; HTTP 5xx rate; DocumentDB CPU and connection count; Bedrock throttling and invocation errors (the InvocationThrottles and InvocationClientErrors CloudWatch metrics under AWS/Bedrock); Textract throttling; and the startup error line above. Verification steps:

curl -s https:///health # expect {"status":"healthy"}

curl -s https:/// # expect a JSON banner, version 1.0.1

curl -s -o /dev/null -w '%{http_code}\n' https:///docs # expect 200

curl -s https:///auth/ms/login_url

aws bedrock list-foundation-models --region <BEDROCK_REGION>
--query "modelSummaries[?contains(modelId,'anthropic')].modelId" --output text

If step 3 returns 404, ROOT_PATH is still /hcc-icd and every path is prefixed.

9. Service quotas, IAM and pricing Service quotas - request increases proactively via Service Quotas:

Amazon Bedrock per-model requests-per-minute and tokens-per-minute is the primary scaling constraint for extraction. Throttling surfaces as ThrottlingException; raise the quota or adopt a cross-Region inference profile to spread load. Amazon Textract transactions per second bound OCR throughput. Also monitor EKS nodes or ECS tasks, and DocumentDB instances and connections. IAM (least privilege). The role listed in Section 4, step 3 is the complete set. Bind it with IRSA on EKS or as taskRoleArn on ECS. On ECS the separate execution role additionally needs ECR pull and secret-read permissions; on EKS the node role needs ECR pull.

DocumentDB needs no IAM permission. Even though the service authenticates to it with this same role, access is granted inside the database by mapping the role ARN to a DocumentDB user (Section 5). Adding IAM permissions will not fix a DocumentDB authorization failure, and rds-db:connect is an Amazon RDS action that does not apply to DocumentDB.

Pricing - software is billed through AWS Marketplace at the listed rate. You separately pay standard AWS rates for the infrastructure you run it on: EKS or ECS compute, DocumentDB, S3, Secrets Manager, the load balancer, CloudWatch, Amazon Bedrock per-token inference, and Amazon Textract per-page OCR. Bedrock token spend is typically the largest variable cost. Because every dependency is an AWS service, the whole deployment can be modeled in the AWS Pricing Calculator.

10. Security and compliance (PHI) This product processes Protected Health Information. Every service in the data path is an AWS service, so a single AWS Business Associate Addendum covers it. To operate in a HIPAA-eligible manner:

Execute an AWS Business Associate Addendum and use HIPAA-eligible AWS services. Amazon Bedrock, Amazon Textract, Amazon DocumentDB, Amazon S3, Amazon EKS, Amazon ECS, and AWS Secrets Manager are all HIPAA-eligible. Enable KMS encryption at rest and TLS in transit; run workloads and data stores in private subnets, exposing only the load balancer. Use VPC endpoints for Bedrock, Textract, S3, and Secrets Manager so PHI-bearing traffic never traverses the public internet. Restrict the container security group so port 8000 is reachable only from the load balancer. Restrict CORS to your frontend origin at the ingress. The application ships with a permissive CORS configuration, so origin filtering should be enforced in front of it. Scope the IAM role to least privilege and keep the container non-root. Application code and the CA bundle are already shipped read-only. Do not enable debug logging that could capture PHI. Enable Bedrock model invocation logging to CloudWatch or S3 if your compliance program requires an inference audit trail. Those logs contain prompts and completions, so treat the destination as PHI storage. 11. Upgrades and release notes Upgrades are a rolling image replacement with no destructive migration:

Review the release notes for the target version and any new or changed configuration. Snapshot DocumentDB and confirm S3 versioning. Pull the new image tag and update the Deployment or ECS service. Update the batch processor's task to the same tag so both run the same version. Verify with the checks in Section 8, including the startup log line - a passing /health alone does not prove a good upgrade. Roll back to the prior tag if needed; rollback is immediate since no destructive migration runs. If a release changes the default BEDROCK_MODEL_ID, confirm you have been granted access to the new model in Amazon Bedrock for your Region before rolling out.

Release notes (v1.0.1 - initial release): ICD-10-CM extraction backed by the 2025 code set, midyear mappings, and coding guidelines; HCC and RxHCC risk scoring; coder and auditor workflow with capacity limits, draft and final states, and change-log auditing; claims and reporting; ICD search; admin configuration for risk scores, workflow, roles, and UI features; clinical-document OCR via Amazon Textract; LLM extraction via Claude models on Amazon Bedrock; and a batch processor for bulk ingestion. Hardened non-root container on Python 3.11 with application code and certificates shipped read-only, and TLS-enforced DocumentDB connectivity with passwordless IAM authentication. Future releases are labeled Critical (security), Important, or Optional.

12. Support This product is provided by Penguin AI. For product support, questions, or issues, contact support@penguinai.co . AWS infrastructure issues are handled through AWS Support. A running instance serves its interactive API reference at /docs and /redoc.