Penguin Ai - Intelligent Revenue Cycle Management

1. Product overview A HIPAA-aware backend service that automates healthcare revenue-cycle pre-submission review. It verifies patient eligibility over X12 270/271, ingests 837P/837I claims, scrubs them through a JSON-driven rules engine, and produces explainable findings with citations and a replayable audit trail.

Key capabilities: eligibility verification with a pluggable clearinghouse adapter; a pre-submission rules engine that returns cited, explainable findings; a review worklist that ranks claims by deny risk and timely-filing deadline; claim lifecycle management with correction disposition and an optional supervisor approval gate; batch export over local, SFTP, or S3 transport; a full audit trail with per-request correlation IDs; and pluggable reference-data providers for credentialing, NCCI bundling, coding accuracy, fee schedule, medical necessity, place-of-service, and admission status.

The service exposes a REST API (OpenAPI/Swagger) and runs from a single container image in two roles: an API server and one or more optional background workers.

2. Product at a glance Runtime: FastAPI + Uvicorn (Python 3.12), non-root container (uid 1000) Listening port: 8000/tcp (HTTP, behind a TLS-terminating load balancer) Health endpoints: GET /api/v1/health (liveness, unauthenticated, no PHI); GET /api/v1/ready (readiness - probes the datastore and cache) API docs: GET /docs, GET /redoc API prefix: /api/v1 State: stateless - all persistent data lives in external, buyer-owned AWS services Volumes: none required Version: 0.1.0

3. Prerequisites Provision the following in your own account and supply their coordinates via environment variables:

Amazon DocumentDB (MongoDB-compatible, TLS) - primary datastore: claims, findings, rules, users, sessions, audit logs. Redis (Amazon ElastiCache) - rule cache and idempotency keys, and the task broker and result backend when background workers are enabled. Required in all configurations, not only when workers are used. Microsoft Entra ID app registration (OAuth 2.0 confidential client with a Web redirect URI and a client secret) - sign-in and role mapping. Amazon ECS or EKS + Application Load Balancer - runtime and HTTPS termination. Optional, depending on which capabilities you enable:

X12 clearinghouse account (Stedi) - live 270/271 eligibility transactions. Without one, the eligibility provider runs in mock mode and returns fixture data, which is sufficient for evaluation. Amazon S3 bucket or an SFTP host - destination for batch claim export. Reference-data provider endpoints and keys - for the credentialing, bundling, coding, fee schedule, medical necessity, POS/TOB, and admission-status families. Each ships defaulted to mock or local. Keep DocumentDB and ElastiCache in the same VPC and Region as the compute.

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//rcm-platform:0.1.0 Provision the prerequisites in Section 3.

Store secrets (DocumentDB and Redis passwords, Entra client secret, clearinghouse and provider API keys, export credentials) in AWS Secrets Manager or SSM Parameter Store and inject them as environment variables. Never bake secrets into the image.

Deploy on ECS or EKS:

Run one API service on container port 8000 behind an ALB with health check path /api/v1/health. Do not override the image's default command; it starts the API correctly. Optionally run one or more worker services from the same image with the command celery -A app.worker.celery_app:celery_app worker --loglevel=info --concurrency=2, plus a scheduled sweep task. Workers open no ports. See Section 5 for choosing a background model. Give the pods an AWS identity: an IRSA role on EKS (a ServiceAccount annotated with eks.amazonaws.com/role-arn, referenced by serviceAccountName on all three workloads), or the task role on ECS. It needs s3:PutObject only when S3 export is enabled, and no permissions at all otherwise (Section 9). On Amazon ECS, register a Fargate task definition with networkMode: awsvpc, 1 vCPU / 2 GB, a port mapping on container port 8000, non-secret settings in environment, secret settings in secrets referencing your Secrets Manager ARNs, awslogs log configuration, and a container health check. The image's slim base has no curl, so use the Python probe the image itself declares:

python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/api/v1/health ').status==200 else 1)" On Amazon EKS, ready-to-use Kustomize manifests ship with the product in k8s/ (Deployment, Service, Ingress, HorizontalPodAutoscaler, PodDisruptionBudget, and the optional worker Deployment, KEDA ScaledObject, and sweep CronJob). Create the namespace, create the Secret from k8s/base/secret.example.yaml, point the manifests at your image with kustomize edit set image rcm=<IMAGE_URI>, replace the placeholder hostnames and endpoints in the overlay, then kubectl apply -k k8s/overlays/prod. The prod overlay expects ingress-nginx, cert-manager, and KEDA to be installed; the dev overlay omits the KEDA ScaledObject.

Seed the rule catalog. Environments other than prod seed the pre-submission rule catalog automatically at startup. When RCM_ENV=prod, run the seed once after the first deployment - otherwise GET /api/v1/rules returns an empty list and claims produce no findings. The operation is idempotent, so re-run it after each upgrade to pick up new or changed rules:

kubectl exec -i -n deploy/rcm-api -- python - <<'PY' import asyncio from app.core.config import get_settings from app.adapters.db.mongo import init_mongo from app.adapters.cache.redis_cache import init_redis from app.core.container import Container from app.engine.catalog import seed_pre_rules

async def main(): s = get_settings() await init_mongo(s.mongo_uri, s.mongo_db) await init_redis(s.redis_uri) await seed_pre_rules(Container.build(s).rule_service)

asyncio.run(main()) PY On ECS, run the same script as a one-off task with a containerOverrides command. On a plain Docker host, substitute docker exec -i rcm-api.

Verify. Confirm the service is healthy, then:

curl https:///api/v1/health

curl -i https:///api/v1/ready

curl https:///api/v1/rules

Then POST a sample eligibility request to /api/v1/eligibility/submit (see examples/payloads/submit_request.json, a terminated-coverage scenario with an exhausted physical-therapy benefit):

curl -X POST https:///api/v1/eligibility/submit
-H 'Content-Type: application/json'
--data-binary @examples/payloads/submit_request.json Expect HTTP 201 and a body containing request_id, evaluation_id, the normalized canonical eligibility record, a results array, and a summary whose evaluated_count is greater than zero and whose matched_count is 2. Those two matches are R-01-01 (coverage terminated before the date of service) and R-01-12 (plan benefit exhausted), each returned with its citation, CARC code, and recommended action. Rule states serialize in upper case - MATCHED, NOT_MATCHED, UNKNOWN.

This confirms eligibility normalization and rule evaluation end to end. It requires no authentication, so it can be run before SSO is configured.

Open https:///docs for the interactive API reference, and complete an SSO sign-in to confirm end-to-end authentication.

Scale by running additional API and worker containers behind the load balancer. The API is stateless and scales horizontally; the shipped Kubernetes HPA targets 70% CPU.

5. Configuration (high level) Configuration is entirely environment-variable driven and every variable is prefixed RCM_. There is no configuration file to mount. The main groups are:

Datastore: RCM_MONGO_URI, RCM_MONGO_DB. DocumentDB requires TLS and retryWrites=false; the CA certificate is already inside the image, so reference it directly - mongodb://:27017/?tls=true&tlsCAFile=/app/global-bundle.pem&retryWrites=false&replicaSet=rs0. Passwordless IAM authentication is supported by adding authMechanism=MONGODB-AWS&authSource=$external and omitting credentials entirely.

Cache and broker: RCM_REDIS_URI, plus RCM_CELERY_BROKER_URL and RCM_CELERY_RESULT_BACKEND when workers are enabled (these default to separate Redis logical databases so queue traffic never collides with the application cache). Use the rediss:// scheme when ElastiCache in-transit encryption is enabled.

Authentication: RCM_ENTRA_TENANT_ID, RCM_ENTRA_CLIENT_ID, RCM_ENTRA_CLIENT_SECRET, and RCM_BOOTSTRAP_ADMIN_EMAILS. The bootstrap list auto-provisions those addresses as active administrators on first sign-in and must be set before anyone signs in - otherwise no administrator account exists and the admin routes are unreachable. Sessions are server-side with a configurable lifetime (RCM_SESSION_TTL_SECONDS); the API issues a session cookie rather than a bearer token, so set RCM_SESSION_COOKIE_SECURE=true on HTTPS and RCM_SESSION_COOKIE_SAMESITE=none when the UI and API are on different sites.

By default (RCM_ENTRA_REDIRECT_FROM_REQUEST=true) the OAuth redirect URI is derived per sign-in from the browser's origin plus RCM_ENTRA_REDIRECT_PATH (default /callback), so one configuration works across environments - register https:///callback in Entra. Set that flag to false to pin the static RCM_ENTRA_REDIRECT_URI instead. Whichever value is sent must match a registered Web redirect URI exactly or sign-in fails with AADSTS50011, and Entra rejects http:// for any host other than localhost.

Web and CORS: RCM_CORS_ORIGINS (comma-separated or JSON array), RCM_CORS_ORIGIN_REGEX, RCM_FRONTEND_URL, and RCM_ROOT_PATH when served behind a proxy sub-path. The built-in CORS defaults are development origins and will not match a buyer deployment.

Eligibility and reference data: RCM_ELIGIBILITY_PROVIDER plus its key and base URL, and one provider selector per reference-data family. All of these default to mock or local, so an unconfigured deployment does not call those external services.

Export: RCM_EXPORT_TRANSPORT (local, sftp, or s3) with the matching SFTP or S3 settings.

Security and ops: RCM_ENV (dev, test, stage, prod), RCM_LOG_LEVEL, RCM_LOG_JSON.

Ports. 8000/tcp is the only listening port. Worker and sweep containers open no ports; they pull work from Redis. The bundled Kubernetes Service listens on port 80 and forwards to container port 8000.

Volumes. None are required - the container writes no durable data. Two exceptions worth noting: the DocumentDB CA certificate is already baked into the image at /app/global-bundle.pem and must not be mounted, and a writable volume is needed only if you set RCM_EXPORT_TRANSPORT=local, where artifacts are written to RCM_EXPORT_LOCAL_DIR (default ./var/exports) and the mount must be writable by uid 1000. On AWS, RCM_EXPORT_TRANSPORT=s3 avoids this entirely and is recommended.

Background processing - enable exactly one model. Batch release and claim rechecks run either in-process (RCM_EXPORT_SCHEDULER_ENABLED=true, no additional containers; safe across replicas because each batch is atomically claimed) or through Celery workers (RCM_CLAIM_PROCESSING_ASYNC=true with worker containers and the sweep schedule). Enabling both double-processes the release window. The bundled Kubernetes manifests ship configured for the Celery model, which is why KEDA is a prerequisite of the prod overlay; remove the three worker resources from k8s/base/kustomization.yaml to run the API alone.

Optional feature flags gate modules such as clinical ingest, the supervisor approval gate, and automatic rechecks on ingestion; leave them at defaults unless enabling a specific capability.

6. Data, sensitive information and encryption Where data is stored - the container holds no durable data:

Claims, findings, rules, users, sessions, audit logs -> Amazon DocumentDB (buyer-owned). Batch export artifacts -> Amazon S3 or your SFTP destination (buyer-owned). Rule cache, idempotency keys, and task queue data -> Redis (ephemeral). Secrets -> AWS Secrets Manager / SSM (buyer-owned). Uploaded 837P/837I claim files are parsed in memory and persisted only as structured records in DocumentDB; the container writes no PHI to local disk.

Encryption:

In transit: TLS everywhere - the ALB terminates HTTPS to clients; DocumentDB connections enforce TLS using the CA bundled in the image; enable in-transit encryption for ElastiCache and use the rediss:// scheme; all AWS SDK calls use HTTPS. At rest: enable AWS KMS encryption on DocumentDB, S3, ElastiCache, and Secrets Manager when you provision them. Decryption: the application uses no proprietary encryption. Managed services transparently decrypt for the container's IAM role. The session cookie carries only an opaque session identifier, with no PHI and no claim data; the session record itself lives server-side in DocumentDB. 7. Credentials and rotation Store all credentials in Secrets Manager / SSM and rotate on a regular cadence (align to your security policy, typically 90 days or less):

Entra client secret (RCM_ENTRA_CLIENT_SECRET) - rotate before expiry; overlap old and new during cutover. Existing user sessions are server-side and are not invalidated by rotation. DocumentDB / Redis passwords - use managed rotation and redeploy so all services pick up the new value. Prefer passwordless DocumentDB IAM authentication where possible, which removes this credential entirely. Clearinghouse and reference-data API keys, and export SFTP keys or S3 credentials - rotate before expiry; overlap old and new during cutover. AWS access: use IAM task roles / IRSA - avoid long-lived access keys. Procedure: update the secret -> rolling redeploy of the API and all workers -> confirm health -> revoke the old value.

8. Backup, recovery and health Backup / recovery (standard, non-proprietary stores):

DocumentDB (system of record): enable automated snapshots and point-in-time recovery; restore to a new cluster and repoint the connection string. Required indexes are re-created automatically at startup, and the rule catalog can be re-seeded idempotently (Section 4, step 5). S3: enable versioning, and optional cross-Region replication for DR. Redis: treated as ephemeral; cached rules are rebuilt on demand and in-flight work is re-driven from DocumentDB state. Because the container is stateless, DR is: restore DocumentDB and S3, redeploy the image, repoint environment variables.

Health monitoring:

In the ECS/EKS console, confirm running count equals desired count and tasks/pods are healthy (the container has a built-in health check and the ALB checks /api/v1/health). Call GET /api/v1/health for a fast liveness signal. It deliberately does not probe downstreams, so downstream slowness never falsely marks the API down. Call GET /api/v1/ready for readiness and for diagnosing connectivity. It pings DocumentDB and Redis and returns HTTP 503 with {"status":"degraded","checks":{...}} naming the failing dependency. Send container logs to CloudWatch Logs. Logs are structured JSON and PHI-safe at the default INFO level, and every request carries a correlation ID that traces it end to end. Recommended alarms: unhealthy target hosts; service running count below desired; /api/v1/ready returning 503; HTTP 5xx rate; DocumentDB and ElastiCache CPU and connection counts; and clearinghouse or reference-data provider error rates. 9. Service quotas, IAM and pricing Service quotas - request increases proactively via Service Quotas:

Your X12 clearinghouse transactions-per-second limit is the primary external scaling constraint for live eligibility verification; this is set by that vendor, not AWS. Also monitor ECS/Fargate tasks, DocumentDB instances and connections, ElastiCache nodes, and ALB rules and targets. IAM (least privilege). On EKS, bind the pods to an IAM role with IRSA (IAM Roles for Service Accounts): annotate the ServiceAccount used by the API, worker, and sweep workloads with eks.amazonaws.com/role-arn, and set serviceAccountName on each pod spec. On ECS, the equivalent is the task role (taskRoleArn). Either way, avoid long-lived access keys.

The application's entire AWS API surface is a single s3:PutObject, so the attached permissions policy is correspondingly small:

{ "Effect": "Allow", "Action": "s3:PutObject", "Resource": "arn:aws:s3:::<EXPORT_BUCKET>/<EXPORT_PREFIX>*" } Add kms:GenerateDataKey and kms:Encrypt on the bucket's key only if the export bucket uses SSE-KMS. If you leave RCM_EXPORT_TRANSPORT at its default, the role needs no permissions policy at all - it only has to exist as an identity.

The role does not need Secrets Manager, SSM, or kms:Decrypt: the application never reads a secret through the AWS SDK. Secrets arrive as environment variables, and if you source them from AWS, the External Secrets Operator or Secrets Store CSI Driver uses its own role, not this one. It does not need CloudWatch permissions either, since logs are written to stdout and collected by the platform.

DocumentDB IAM authentication is authorized in the database, not in IAM. No IAM policy grants it, and rds-db:connect does not apply to DocumentDB. The role is only an identity; access is granted by creating a DocumentDB user named for the role ARN:

use $external; db.createUser({ user: "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>", mechanisms: ["MONGODB-AWS"], roles: [ { role: "readWrite", db: "rcm" } ] }); This requires an instance-based DocumentDB 5.0 cluster, cannot be used for the cluster's primary user, and makes an STS GetCallerIdentity call per new connection. In the connection string, $ must be URL-encoded: authSource=%24external.

The ECS execution role (distinct from the task role) additionally needs ECR pull and secret-read permissions.

Pricing - software is billed through AWS Marketplace at the listed rate. You separately pay standard AWS rates for the infrastructure you run it on: ECS/EKS compute, DocumentDB, ElastiCache, S3, the load balancer, Secrets Manager, and CloudWatch. Per-transaction clearinghouse charges for live 270/271 eligibility are billed by that vendor and are separate from both. Estimate with the AWS Pricing Calculator; compute and DocumentDB sizing dominate total AWS cost.

10. Security and compliance (PHI) This product processes Protected Health Information. To operate it in a HIPAA-eligible manner: execute an AWS Business Associate Addendum and use HIPAA-eligible services; enable KMS encryption at rest and TLS in transit; run all containers and data stores in private subnets exposing only the ALB; restrict the container security group so port 8000 is reachable only from the load balancer; keep the container non-root; scope IAM to least privilege; restrict RCM_CORS_ORIGINS to your own origins; set RCM_SESSION_COOKIE_SECURE=true; keep RCM_LOG_LEVEL above DEBUG so claim payloads are not written to logs; and retain the DocumentDB audit trail per policy.

11. Upgrades and release notes Upgrades are a rolling image replacement with no data migration (indexes are ensured idempotently at startup):

Review release notes for the target version and any new required environment variables. Snapshot DocumentDB and confirm S3 versioning before upgrading production. Pull the new image tag and roll out the API and all worker services to the same version. Re-run the rule-catalog seed (Section 4, step 5) so any new or changed rules are applied. It is idempotent. Verify health and run a smoke test. Roll back to the prior image tag if needed - rollback is immediate since no destructive migration runs. Release notes (v0.1.0 - initial release): eligibility verification over X12 270/271 with a pluggable clearinghouse adapter; a JSON-driven pre-submission rules engine producing cited, explainable findings with field-presence pruning; a review worklist ranked by deny risk and timely-filing deadline; claim lifecycle with correction disposition and an optional supervisor approval gate; batch export over local, SFTP, or S3 transport; a replayable audit trail with per-request correlation IDs; and pluggable reference-data providers. Hardened non-root container on Python 3.12 with TLS-enforced database connectivity, Microsoft Entra ID SSO using server-side sessions, and structured PHI-safe logging. 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.