Penguin Ai - Intelligent Medical Coding

1. Product overview A HIPAA-aware backend service that automates two home-health workflows: ICD medical coding and OASIS scrubbing. It ingests clinical documents and episode data, performs OCR and PHI-aware extraction, and uses Claude models on Amazon Bedrock to suggest ICD codes and OASIS corrections with supporting evidence.

Key capabilities: ICD code suggestion with evidence and expert review; coding-session dashboards and review statistics; OASIS episode scrubbing with guideline decisions, accuracy breakdown, and episode lock/submit; clinical-document OCR; enterprise data-warehouse integration for episode data; and an EKS-native batch runner in which the API launches one Kubernetes Job per episode or run date on demand.

The service runs entirely on AWS services. It exposes a REST API (OpenAPI/Swagger) and runs from a single container image; the same image serves the API and the batch Jobs it launches.

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) Route prefixes: /icd-coding/v2, /icd-coding/v2/auth, /oasis-scrubbing API docs: GET /docs, GET /redoc, GET /openapi.json Health endpoint: none is published; use GET /docs (or /openapi.json) as the load balancer health check path. See Section 8. Authentication: JWT bearer token from POST /icd-coding/v2/auth/login State: stateless - all persistent data lives in external, buyer-owned AWS services Volumes: none required Orchestration: Amazon EKS is required for batch episode dispatch. See Section 4. Version: 1.0.0

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

Amazon EKS - required. The API creates Kubernetes Jobs in its own namespace to process episodes, so it must run in a cluster with the RBAC in Section 4. Amazon DocumentDB (MongoDB-compatible, TLS) - users, coding results, OASIS results, and field-encrypted values. 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 IRSA role instead of a stored password (Section 5). Amazon Bedrock with Claude model access enabled in the deployment Region - the inference engine for ICD code suggestion and OASIS scrubbing. 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 pod's IAM role (Section 9). Amazon S3 - reference resources, source documents, and generated artifacts. The bucket must contain oasis_resources.zip at its root before startup; see the warning in Section 4. AWS Secrets Manager - holds the configuration bundle. Read through the pod's IRSA role. Application Load Balancer / Ingress with a TLS certificate forwarding to port 8000. Optional, depending on the capabilities you enable:

A data warehouse (for example Amazon Redshift or Snowflake) as the source of home-health episode data, configured from the ACC_SNOWFLAKE_* keys in the configuration bundle. HCHB integration - configured with ACC_HCHB_AGENCY_SECRET. Amazon ElastiCache for Redis - passed through to batch Jobs as REDIS_URL when set. Keep DocumentDB, S3, Bedrock, Textract, and the EKS cluster in the same Region so that inference and OCR calls 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//accentcare-coding:1.0.0 Provision the prerequisites in Section 3. Enable Claude model access in Amazon Bedrock for your deployment Region before the first run.

Upload the reference-resource bundle. At startup the service downloads oasis_resources.zip from the root of your S3 bucket and unpacks it. If that download fails, the API still starts and ICD coding still works, but the entire /oasis-scrubbing route group is silently omitted - its endpoints return 404 with only a warning in the log. Confirm the object exists before you deploy, and check the startup log line Downloading resources from s3:///oasis_resources.zip.

Create the configuration bundle in Secrets Manager. The service reads a single JSON secret named accentcare- (for example accentcare-prod when ENV=prod). See Section 5 for its keys.

Deploy on Amazon EKS:

Run the API as a Deployment on container port 8000 behind an Ingress with TLS, using GET /docs as the health check path. Do not override the image's command; the default (uvicorn main:app --host 0.0.0.0 --port 8000) starts the API correctly. Bind the pod to a ServiceAccount that has both: Kubernetes RBAC to dispatch Jobs in its own namespace: get on pods, get/list/watch on pods/log, and create/get/list/watch/delete on batch/jobs. A ready-made Role and RoleBinding ship in k8s/oasis-runner.yaml. IRSA for AWS access - Bedrock, Textract, S3, Secrets Manager, and DocumentDB (Section 9). Job pods reuse the same ServiceAccount and therefore inherit the same role. Configure the batch runner. Set OASIS_RUNNER_IMAGE to the same image tag as the API, and OASIS_RUNNER_SERVICE_ACCOUNT to the ServiceAccount above. If OASIS_RUNNER_IMAGE is unset the API tries to read its own pod spec to discover the image, which only works in-cluster; outside a cluster, episode dispatch fails with "Cannot resolve runner image".

Verify (Section 8): confirm pods are Ready, open https:///docs, obtain a token from POST /icd-coding/v2/auth/login, call a protected endpoint, and confirm a dispatched episode Job completes.

Scale by adding API replicas and by raising episode Job concurrency.

Running outside EKS. The API process itself will start under plain Docker or Amazon ECS, which is useful for a smoke test of authentication and the OpenAPI surface:

docker run -d -p 8000:8000 -e ENV=dev -e AWS_REGION=us-east-2 <IMAGE_URI> Episode dispatch will not work there, because it creates Kubernetes Jobs. Use EKS for any real deployment.

5. Configuration (high level) Configuration resolves in two steps. The service first reads a JSON bundle from AWS Secrets Manager named accentcare-, and if that lookup fails it falls back to an environment variable of the same name (a warning is logged on every fallback). Only a subset of settings has an environment fallback; the rest are bundle-only.

Bootstrap variables. Plain environment variables, read before Secrets Manager:

ENV - selects the bundle name accentcare-. Default dev; set this per environment. AWS_REGION - Region for the Secrets Manager client, and the default Region for Textract and S3. Default us-east-2. Configuration bundle keys, stored in the accentcare- secret. These six are required, and each also accepts an environment variable of the same name as a fallback:

MONGO_URI - DocumentDB connection string. See "Connecting to DocumentDB with IRSA" below. MONGO_DB - database name. Optional; defaults to accentcare. DB_ENCRYPTION_KEY - Fernet key for field-level encryption. Back this up - see Section 6. AWS_BUCKET_NAME - S3 bucket for resources, documents, and artifacts. AWS_REGION - Region used by the application. Optional; defaults to us-east-2. ROOT_PATH - mount prefix when served behind a proxy sub-path, so /docs resolves. Optional; defaults to empty. The remaining bundle keys have no environment-variable fallback and must be present in the secret:

CLAUDE_AWS_REGION - required. The Region whose Amazon Bedrock endpoint serves inference. Set it to a Region where you have enabled Claude model access; it may differ from AWS_REGION if you centralize inference capacity, though keeping them equal avoids cross-Region PHI transfer. CLAUDE_MODEL_ID - required. 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). Whatever you set here must be a model you have been granted access to in CLAUDE_AWS_REGION. REDIS_URL - optional. Passed through to batch Jobs when set. ACC_SNOWFLAKE_* - required for warehouse reads. Ten keys: ACC_SNOWFLAKE_AUTH_CLIENT_ID, ACC_SNOWFLAKE_AUTH_CLIENT_SECRET, ACC_SNOWFLAKE_SCOPE_URL, ACC_SNOWFLAKE_TOKEN_URL, ACC_SNOWFLAKE_USER, ACC_SNOWFLAKE_ACCOUNT, ACC_SNOWFLAKE_ROLE, ACC_SNOWFLAKE_DATABASE, ACC_SNOWFLAKE_SCHEMA, ACC_SNOWFLAKE_WAREHOUSE. All ten must be present, or warehouse access raises an error when that feature first runs. ACC_HCHB_AGENCY_SECRET - required for the HCHB integration. Amazon Textract needs no configuration keys. OCR runs in AWS_REGION and is authorized entirely by the pod's IAM role - there is no endpoint, key, or secret to manage.

Batch runner variables. Plain environment variables on the API pod:

OASIS_RUNNER_IMAGE - recommended. The image dispatched Jobs run; set it to the same tag as the API. If unset, the API reads its own pod spec to discover the image, which only works in-cluster. OASIS_RUNNER_SERVICE_ACCOUNT - recommended. ServiceAccount assigned to Job pods, so they inherit the same IRSA role. K8S_NAMESPACE - optional, fallback only. In-cluster the namespace is read from the projected ServiceAccount token; this variable is used only when that file is absent, and defaults to default. RUN_DATE - optional. Pins the processing date for batch runs. These variable names are historical: OASIS_* configures the batch Job runner used by both ICD episode dispatch and OASIS scrubbing, and must be set under exactly these names.

Connecting to DocumentDB with IRSA. Authenticate to Amazon DocumentDB with IAM authentication through the pod's IRSA 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. Include it in the URI rather than relying on the application, because not every internal call site passes it as a client option. 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 pod's IRSA role by the AWS credential chain. Authorization is granted in the database, not in IAM. No IAM policy grants DocumentDB access; the IRSA role is only an identity. 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/<IRSA_ROLE_NAME>", mechanisms: ["MONGODB-AWS"], roles: [ { role: "readWrite", db: "accentcare" } ] }); Dispatched Job pods reuse the same ServiceAccount and therefore the same role, so this single grant covers the API and every batch Job. It also means MONGO_URI carries no secret when it is passed into Job manifests.

Constraints to check before choosing this path:

IAM authentication requires an instance-based DocumentDB 5.0 cluster. It cannot be used for the cluster's primary user, which stays password-based. Each new connection causes the cluster to call STS GetCallerIdentity, so very high connection churn can hit STS throttling. If your cluster cannot meet those constraints, fall back to a password in MONGO_URI, keep that value in the Secrets Manager bundle, and rotate it as described in Section 7.

Ports: 8000/tcp is the only listening port. Dispatched Job pods expose no ports.

Volumes: none are required. The container writes no durable data. Transient PDFs and OCR output are written inside the container and removed after use. The DocumentDB CA is already in the image at /app/global-bundle.pem, and the Playwright Chromium build used for PDF rendering is at /opt/playwright; neither should be mounted over.

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:

Users, coding results, OASIS results, and audit records go to Amazon DocumentDB (buyer-owned). Source documents, reference resources, and generated artifacts go to Amazon S3 (buyer-owned). Configuration and credentials 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.

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. Field-level: sensitive values are encrypted with Fernet (DB_ENCRYPTION_KEY) before being written to DocumentDB. DB_ENCRYPTION_KEY is not recoverable. Values encrypted with it cannot be read without it. Back it up securely and treat rotation as a planned migration - see Section 7.

7. Credentials and rotation Because inference, OCR, storage, and the database all authenticate through the pod's IAM role, there are very few long-lived secrets to manage. Store what remains in Secrets Manager and rotate on your normal cadence (90 days or less):

DB_ENCRYPTION_KEY - rotating this key requires re-encrypting every existing field-encrypted value in DocumentDB during a planned window. Rotating it without that migration makes the existing data unreadable. DocumentDB credentials - with IAM authentication through IRSA (Section 5) there is no database password to rotate; the driver obtains short-lived credentials from the role on every connection. If you instead embedded a password in MONGO_URI, use managed rotation, then redeploy the API and confirm dispatched Jobs pick up the new value. Warehouse and HCHB credentials - rotate before expiry. 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. Avoid long-lived access keys. global-bundle.pem in the image is a public certificate authority bundle, not a secret.

Procedure: update the secret, roll the API Deployment, confirm health, then revoke the old value. Note that secret reads are cached in-process, so a rolling restart is required for a new value to take effect.

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. Restored data is unreadable without the matching DB_ENCRYPTION_KEY. Amazon S3: enable versioning, and cross-Region replication if you need regional DR. Keep oasis_resources.zip in any replacement bucket. Secrets Manager: secrets are the other half of a working restore; include them in your DR runbook. 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:

This service publishes no dedicated health endpoint. Use GET /docs or GET /openapi.json as the readiness and load-balancer health check path: both return HTTP 200 once the application is serving and require no authentication. If you set ROOT_PATH, the path moves under that prefix. A 200 from /docs means the process is up. It does not prove DocumentDB, S3, Bedrock, or Textract are reachable; verify those with the functional checks below. In the EKS console or with kubectl get pods, confirm running replicas match desired. Confirm batch Jobs complete: kubectl get jobs -n . Jobs are created with backoffLimit: 0 and ttlSecondsAfterFinished: 300, so a failed Job does not retry and a finished Job is garbage-collected after five minutes. Ship Job logs to CloudWatch if you need to retain them. Send container logs to CloudWatch Logs. Recommended alarms: pod crash-loops and restarts; replicas below desired; failed Jobs; DocumentDB CPU and connection count; Bedrock throttling and invocation errors (the InvocationThrottles and InvocationClientErrors CloudWatch metrics under AWS/Bedrock); Textract throttling; and the startup warning Failed to extract resources - OASIS functionality disabled. Verification steps:

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

curl -s https:///openapi.json | grep -c '/oasis-scrubbing' # expect > 0

curl -s -X POST https:///icd-coding/v2/auth/login
-H 'Content-Type: application/json'
-d '{"username":"","password":""}'

curl -s https:///icd-coding/v2/sessions
-H "Authorization: Bearer <ACCESS_TOKEN>" # expect 200

kubectl get jobs -n

aws bedrock list-foundation-models --region <CLAUDE_AWS_REGION>
--query "modelSummaries[?contains(modelId,'anthropic')].modelId" --output text If step 6 returns nothing, or if inference fails at runtime with AccessDeniedException, request Claude model access for that Region in the Amazon Bedrock console.

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 inference. 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 and pod density, DocumentDB instances and connections, and Secrets Manager API rate limits (secret reads are cached, but every new pod reads them). IAM (least privilege, IRSA). The pod ServiceAccount needs:

bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on the Claude model you configured - scope the resource to that model ARN (arn:aws:bedrock:::foundation-model/anthropic.claude-) rather than . If you use a cross-Region inference profile, also allow the action on the inference-profile ARN (arn:aws:bedrock:::inference-profile/) and on the underlying foundation-model ARNs in each Region the profile routes to. textract:DetectDocumentText and textract:AnalyzeDocument for synchronous OCR. Add textract:StartDocumentTextDetection and textract:GetDocumentTextDetection if you enable asynchronous processing of multi-page documents. s3:GetObject, s3:PutObject, and s3:ListBucket on the configured bucket - reference resources, documents, and artifacts. secretsmanager:GetSecretValue on accentcare- - the configuration bundle. kms:Decrypt on the keys protecting those secrets - only if the secrets use a customer-managed key. CloudWatch Logs write permissions - only if pods ship logs directly rather than through a node agent. DocumentDB needs no IAM permission. Even though the service authenticates to it with this same IRSA 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.

The node role (or the EKS node group) needs ECR pull permissions.

Kubernetes RBAC is separate from IAM and is also required - see Section 4, step 5.

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 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, followed by compute and DocumentDB sizing. 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 it depends on is an AWS service, so a single AWS Business Associate Addendum covers the whole data path. To operate it 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, 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 ALB. Use VPC endpoints for Bedrock, Textract, S3, and Secrets Manager so that PHI-bearing traffic never traverses the public internet. Restrict the pod security group so port 8000 is reachable only from the load balancer. Scope IRSA and Kubernetes RBAC to least privilege, and keep the container non-root. Restrict browser origins at the ingress. The application ships with a permissive CORS configuration, so origin filtering should be enforced in front of it. Do not enable debug logging that could capture PHI. Retain DocumentDB audit logs per your policy, and enable Bedrock model invocation logging to CloudWatch or S3 if your compliance program requires an inference audit trail. Note that invocation logs contain prompts and completions, so treat that 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 API Deployment and OASIS_RUNNER_IMAGE to the same tag, so dispatched Jobs run the same version as the API. Verify with the checks in Section 8, including one dispatched episode Job. Roll back to the prior tag if needed; rollback is immediate since no destructive migration runs. If a release changes the default CLAUDE_MODEL_ID, confirm you have been granted access to the new model in Amazon Bedrock for your Region before rolling out.

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.