Technical Design

Architecture Overview

Zango App: patientbilling
├── backend/
│   ├── patients/     ← Patient CRUD
│   ├── claims/       ← Claim + ClaimLineItem + InsurancePayer + ClaimWorkflow
│   ├── invoices/     ← Invoice + InvoiceLineItem + Payment + InvoiceWorkflow
│   ├── agents/       ← AI tools, Celery tasks, agent wiring
│   └── app/          ← Serves React build
├── frontend/
│   └── src/custom/pages/
│       ├── ClaimsPage.jsx      (CrudHandler + WorkflowStatus + AI Insights tab)
│       ├── PatientsPage.jsx    (profile detail + Claims + Invoices sub-tables)
│       ├── InvoicesPage.jsx    (CrudHandler + WorkflowStatus + payment progress)
│       └── Dashboard.jsx       (summary cards, denial rate, pending revenue)
├── static/js/
├── settings.json
└── manifest.json

Roles

Role	Permissions
BillingStaff	Create/edit patients, claims, invoices; record payments; view AI insights
BillingManager	All above + approve/deny claims, void invoices, dashboard access

Claim Lifecycle (ClaimWorkflow)

Draft ──► Submitted ──► Under Review ──► Approved
                    └──► Denied ────► Appealed ──► Closed
                                   └────────────► Closed

Key transitions:

Draft → Submitted (done()): fires run_claim_validator Celery task
→ Denied (form transition): collects denial_reason_code + description; done() fires run_denial_analyzer AND run_appeal_drafter concurrently

Invoice Lifecycle (InvoiceWorkflow)

Draft ──► Sent ──► Partially Paid ──► Paid
              ├──► Overdue ────────► Paid
              └──► Voided

Concurrent Agent Architecture

# backend/claims/workflows.py — denial transition done() method
def done(self):
    from zango.core.tasks import zango_task_executor
    tenant = self.object_instance.created_by.UserTenantObject.all()[0].tenant.name
    # Both tasks dispatched simultaneously — run on separate Celery workers
    zango_task_executor.delay(
        tenant,
        "backend.agents.tasks.run_denial_analyzer",
        claim_id=str(self.object_instance.id)
    )
    zango_task_executor.delay(
        tenant,
        "backend.agents.tasks.run_appeal_drafter",
        claim_id=str(self.object_instance.id)
    )

AI Agents

Agent	Trigger	Output field	Prompt focus
ClaimValidator	Draft → Submitted	`ai_validation_result` (JSON)	Completeness, ICD-10 validity, CPT suggestions, score 0-100
DenialAnalyzer	→ Denied (concurrent)	`ai_denial_analysis` (JSON)	Root cause, category (eligibility/coding/auth), corrective actions
AppealDrafter	→ Denied (concurrent)	`ai_appeal_draft` (Text)	Formal appeal letter: date, member ID, claim no., medical necessity argument

Architecture Overview

Roles

Claim Lifecycle (ClaimWorkflow)

Invoice Lifecycle (InvoiceWorkflow)

Concurrent Agent Architecture

AI Agents

Tools (backend/agents/tools.py)