# vitthalhumbe/ciphercrew-claimcraft architecture

> Architecture diagram of the GitHub repository vitthalhumbe/ciphercrew-claimcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vitthalhumbe/ciphercrew-claimcraft
- Repository: https://github.com/vitthalhumbe/ciphercrew-claimcraft

## Overview

1. **Overall shape**
   - ClaimCraft is a two-tier application: a **Python/FastAPI backend** that does all parsing, validation, reconciliation, and AI-assisted analysis, and a **React/Vite frontend** that presents upload, inspection, batch, and reconciliation workflows.
   - The repository is organized around a healthcare EDI domain, not a generic CRUD app.

2. **Backend entry point and API boundary**
   - `backend/app.py` is the FastAPI entry point.
   - The backend is split into route modules under `backend/routes/`, each exposing one functional boundary: `parse`, `validate`, `chat`, `reconcile`, `export`, and `autofix`.
   - This makes the API layer thin; the real domain logic lives in `backend/edi_parser/`.

3. **EDI parsing core**
   - `backend/edi_parser/core.py` handles the low-level EDI mechanics: delimiter detection, tokenization, and the parser state machine.
   - The parsing model is intentionally single-pass and stack-based, so the data flow is: raw EDI text → segments → hierarchical loop structure.
   - This is the main architectural engine behind all transaction types.

4. **Transaction-specific parsers**
   - `backend/edi_parser/parsers/` contains separate parsers for **837**, **835**, and **834**.
   - The README describes them as pushdown automata that maintain loop context while traversing segment streams.
   - The parser boundary is important: each transaction type has its own structural rules and output shape, even though they share the same tokenization core.

5. **Validation subsystem**
   - Validation is split into `validator_static.py` and `validator_live.py`, coordinated through `validator.py`.
   - Static validation covers HIPAA 5010 rules, mandatory segments, cross-field consistency, code checks, and deterministic fixes.
   - Live validation adds network-bound reference checks against external services/data sources such as NPI, ICD-10-CM, and HCPCS/CPT lookup data.
   - This creates a clear separation between **offline rule enforcement** and **online enrichment/verification**.

6. **Reference data and domain lookups**
   - The backend includes embedded reference material like `HCPC2026_APR_ANWEB.txt` and likely loaders in `hcpcs_loader.py`.
   - These files support validation without requiring a database service.
   - The architecture therefore mixes local static reference data with external live registry APIs.

7. **Reconciliation workflow**
   - `backend/routes/reconcile.py` supports matching **835 remittance** data against **837 claims**.
   - This is a distinct analytical path: it is not just parsing or validation, but a comparison pipeline that surfaces billed-vs-paid deltas and adjustment reasons.
   - Architecturally, reconciliation sits on top of parsed transaction objects from both sides of the claim/payment flow.

8. **AI-assisted explanation layer**
   - `backend/routes/chat.py` connects the app to Groq-hosted Llama through the `backend/groq` area.
   - The AI layer is used for contextual explanations of validation errors and file-specific guidance, not for core parsing.
   - That makes it an auxiliary reasoning service attached to the validation/reporting workflow.

9. **Export and autofix boundaries**
   - `backend/routes/export.py` is the output boundary for JSON, CSV, and corrected EDI downloads.
   - `backend/routes/autofix.py` represents a deterministic remediation path where known grammar or rule issues can be corrected automatically.
   - These are post-processing services that consume parser/validator output rather than directly reading raw EDI.

10. **Frontend presentation model**
   - The frontend is a Vite/React app under `frontend/src/`, styled with Tailwind.
   - Key pages map directly to user workflows: `Home` for upload and inspection, `Reconcile` for 835/837 matching, `Batch` for multi-file processing, plus informational pages like `About` and `Team`.
   - Components such as raw EDI views, parsed tree views, validation panels, and reconciliation tables indicate a multi-panel analysis UI rather than a simple form-based app.

11. **Client-side state and API access**
   - `frontend/src/store/useEdiStore.js` is the main shared client state container.
   - Backend calls are centralized rather than scattered, which keeps UI components focused on rendering parsed results and validation findings.
   - The frontend is therefore a consumer of the backend analysis pipeline, not a second source of domain logic.

12. **Deployment topology**
   - The project is built for split deployment: **backend on Railway** and **frontend on Vercel**.
   - `backend/requirements.txt` and `runtime.txt` define the Python runtime side, while `frontend/package.json`, `vite.config.js`, and `vercel.json` define the client build and hosting side.
   - This separation reinforces the architectural boundary between API/service execution and static UI delivery.

Main entry points: [`backend/app.py`](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/app.py) (FastAPI app), [`frontend/src/App.jsx`](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/App.jsx) (Vite app), [`backend/routes/parse.py`](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/parse.py) (Parse API), [`backend/edi_parser/validator.py`](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator.py) (Validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["FastAPI app<br/>entrypoint<br/>[app.py]"]
  node_route_parse["Parse API<br/>route<br/>[parse.py]"]
  node_route_validate["Validate API<br/>route<br/>[validate.py]"]
  node_route_reconcile["Reconcile API<br/>route<br/>[reconcile.py]"]
  node_route_chat["Chat API<br/>route<br/>[chat.py]"]
  node_route_export["Export API<br/>route<br/>[export.py]"]
  node_route_autofix["Autofix API<br/>route<br/>[autofix.py]"]
  node_edi_core{{"EDI core<br/>parser engine<br/>[core.py]"}}
  node_parser_837["837 parser<br/>transaction parser<br/>[parser_837.py]"]
  node_parser_835["835 parser<br/>transaction parser<br/>[parser_835.py]"]
  node_parser_834["834 parser<br/>transaction parser<br/>[parser_834.py]"]
  node_validator["Validator<br/>orchestrator<br/>[validator.py]"]
  node_validator_static["Static rules<br/>validation rules"]
  node_validator_live["Live checks<br/>external validation<br/>[validator_live.py]"]
  node_hcpcs_loader["HCPCS data<br/>reference loader<br/>[hcpcs_loader.py]"]
  node_groq_layer["Groq layer<br/>ai integration"]
end

subgraph group_frontend["Frontend"]
  node_store["UI store<br/>state store<br/>[useEdiStore.js]"]
  node_home_page["Home<br/>page<br/>[Home.jsx]"]
  node_reconcile_page["Reconcile<br/>page<br/>[Reconcile.jsx]"]
  node_batch_page["Batch<br/>page<br/>[Batch.jsx]"]
  node_claims_page["Claims<br/>page<br/>[Claims.jsx]"]
  node_ui_components["UI panels<br/>component set"]
  node_frontend_app["Vite app<br/>spa shell<br/>[App.jsx]"]
end

subgraph group_deploy["Deployment"]
  node_runtime["Python runtime<br/>deployment config<br/>[requirements.txt]"]
  node_hosting["Hosting config<br/>deployment config<br/>[railway.toml]"]
end

node_backend_app -->|"mounts"| node_route_parse
node_backend_app -->|"mounts"| node_route_validate
node_backend_app -->|"mounts"| node_route_reconcile
node_backend_app -->|"mounts"| node_route_chat
node_backend_app -->|"mounts"| node_route_export
node_backend_app -->|"mounts"| node_route_autofix
node_route_parse -->|"uses"| node_edi_core
node_route_parse -->|"dispatches"| node_parser_837
node_route_parse -->|"dispatches"| node_parser_835
node_route_parse -->|"dispatches"| node_parser_834
node_validator -->|"orchestrates"| node_validator_static
node_validator -->|"orchestrates"| node_validator_live
node_validator_static -->|"reads"| node_hcpcs_loader
node_route_validate -->|"invokes"| node_validator
node_route_reconcile -->|"consumes"| node_parser_835
node_route_reconcile -->|"consumes"| node_parser_837
node_route_chat -->|"calls"| node_groq_layer
node_route_export -->|"formats"| node_validator
node_route_autofix -->|"applies"| node_validator_static
node_frontend_app -->|"routes to"| node_home_page
node_frontend_app -->|"routes to"| node_reconcile_page
node_frontend_app -->|"routes to"| node_batch_page
node_frontend_app -->|"routes to"| node_claims_page
node_frontend_app -->|"composes"| node_ui_components
node_home_page -->|"reads/writes"| node_store
node_reconcile_page -->|"reads/writes"| node_store
node_batch_page -->|"reads/writes"| node_store
node_claims_page -->|"reads/writes"| node_store
node_runtime -->|"supports"| node_backend_app
node_hosting -->|"deploys"| node_backend_app

click node_backend_app "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/app.py"
click node_route_parse "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/parse.py"
click node_route_validate "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/validate.py"
click node_route_reconcile "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/reconcile.py"
click node_route_chat "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/chat.py"
click node_route_export "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/export.py"
click node_route_autofix "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/autofix.py"
click node_edi_core "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/core.py"
click node_parser_837 "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/parsers/parser_837.py"
click node_parser_835 "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/parsers/parser_835.py"
click node_parser_834 "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/parsers/parser_834.py"
click node_validator "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator.py"
click node_validator_static "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator_static.py"
click node_validator_live "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator_live.py"
click node_hcpcs_loader "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/hcpcs_loader.py"
click node_groq_layer "https://github.com/vitthalhumbe/ciphercrew-claimcraft/tree/main/backend/groq"
click node_store "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/store/useEdiStore.js"
click node_home_page "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Home.jsx"
click node_reconcile_page "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Reconcile.jsx"
click node_batch_page "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Batch.jsx"
click node_claims_page "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Claims.jsx"
click node_ui_components "https://github.com/vitthalhumbe/ciphercrew-claimcraft/tree/main/frontend/src/components"
click node_frontend_app "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/App.jsx"
click node_runtime "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/requirements.txt"
click node_hosting "https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/railway.toml"

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_backend_app,node_route_parse,node_route_validate,node_route_reconcile,node_route_chat,node_route_export,node_route_autofix,node_edi_core,node_parser_837,node_parser_835,node_parser_834,node_validator,node_validator_static,node_validator_live,node_hcpcs_loader,node_groq_layer toneBlue
class node_store,node_home_page,node_reconcile_page,node_batch_page,node_claims_page,node_ui_components,node_frontend_app toneAmber
class node_runtime,node_hosting toneMint
```

## Components

### Backend

FastAPI service for parsing, validation, reconciliation, and AI-assisted analysis

- [FastAPI app](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/app.py): entrypoint · Backend application entry point that wires the API service together · `backend/app.py`
- [Parse API](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/parse.py): route · HTTP boundary for parsing uploaded EDI · `backend/routes/parse.py`
- [Validate API](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/validate.py): route · HTTP boundary for validation and reporting · `backend/routes/validate.py`
- [Reconcile API](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/reconcile.py): route · HTTP boundary for 835-to-837 claim matching · `backend/routes/reconcile.py`
- [Chat API](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/chat.py): route · AI explanation boundary for validation and file guidance · `backend/routes/chat.py`
- [Export API](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/export.py): route · Output boundary for JSON, CSV, and corrected EDI downloads · `backend/routes/export.py`
- [Autofix API](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/routes/autofix.py): route · Deterministic remediation boundary for known issues · `backend/routes/autofix.py`
- [EDI core](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/core.py): parser engine · Single-pass tokenizer and parser state machine for EDI segments · `backend/edi_parser/core.py`
- [837 parser](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/parsers/parser_837.py): transaction parser · Transaction-specific structural parser for 837 claims · `backend/edi_parser/parsers/parser_837.py`
- [835 parser](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/parsers/parser_835.py): transaction parser · Transaction-specific structural parser for 835 remittance data · `backend/edi_parser/parsers/parser_835.py`
- [834 parser](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/parsers/parser_834.py): transaction parser · Transaction-specific structural parser for 834 enrollment data · `backend/edi_parser/parsers/parser_834.py`
- [Validator](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator.py): orchestrator · Coordinates static and live validation passes · `backend/edi_parser/validator.py`
- [Static rules](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator_static.py): validation rules · Offline HIPAA and structural rule enforcement · `backend/edi_parser/validator_static.py`
- [Live checks](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/validator_live.py): external validation · Network-backed reference lookups and registry verification · `backend/edi_parser/validator_live.py`
- [HCPCS data](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/edi_parser/hcpcs_loader.py): reference loader · Embedded reference data loader for code validation · `backend/edi_parser/hcpcs_loader.py`
- [Groq layer](https://github.com/vitthalhumbe/ciphercrew-claimcraft/tree/main/backend/groq): ai integration · Backend integration area for hosted Llama explanations · `backend/groq`

### Frontend

React/Vite UI for upload, inspection, batch processing, and reconciliation

- [UI store](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/store/useEdiStore.js): state store · Shared client state for EDI workflows and results · `frontend/src/store/useEdiStore.js`
- [Home](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Home.jsx): page · Upload and inspection entry page · `frontend/src/pages/Home.jsx`
- [Reconcile](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Reconcile.jsx): page · 835 and 837 matching workflow page · `frontend/src/pages/Reconcile.jsx`
- [Batch](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Batch.jsx): page · Multi-file processing and review page · `frontend/src/pages/Batch.jsx`
- [Claims](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/pages/Claims.jsx): page · Claim-centric inspection and review page · `frontend/src/pages/Claims.jsx`
- [UI panels](https://github.com/vitthalhumbe/ciphercrew-claimcraft/tree/main/frontend/src/components): component set · Shared viewers, tables, modals, and navigation components · `frontend/src/components`
- [Vite app](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/frontend/src/App.jsx): spa shell · React application shell and client bootstrap · `frontend/src/App.jsx`

### Deployment

Runtime and hosting configuration for split deployment

- [Python runtime](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/requirements.txt): deployment config · Backend runtime and dependency definition · `backend/requirements.txt`
- [Hosting config](https://github.com/vitthalhumbe/ciphercrew-claimcraft/blob/main/backend/railway.toml): deployment config · Split deployment configuration for backend and frontend hosting · `backend/railway.toml`

## Connections

- FastAPI app → Parse API: mounts · Registers parse routes on the API app
- FastAPI app → Validate API: mounts · Registers validation routes on the API app
- FastAPI app → Reconcile API: mounts · Registers reconciliation routes on the API app
- FastAPI app → Chat API: mounts · Registers AI explanation routes on the API app
- FastAPI app → Export API: mounts · Registers export routes on the API app
- FastAPI app → Autofix API: mounts · Registers autofix routes on the API app
- Parse API → EDI core: uses · Parsing API delegates to the EDI parser core
- Parse API → 837 parser: dispatches · Routes 837 payloads to the 837 parser
- Parse API → 835 parser: dispatches · Routes 835 payloads to the 835 parser
- Parse API → 834 parser: dispatches · Routes 834 payloads to the 834 parser
- Validator → Static rules: orchestrates · Runs deterministic validation rules first
- Validator → Live checks: orchestrates · Runs external verification checks when needed
- Static rules → HCPCS data: reads · Uses embedded HCPCS reference data for code checks
- Validate API → Validator: invokes · Validation API calls the validation coordinator
- Reconcile API → 835 parser: consumes · Reconciliation consumes parsed remittance data
- Reconcile API → 837 parser: consumes · Reconciliation consumes parsed claim data
- Chat API → Groq layer: calls · AI chat boundary forwards context to hosted model services
- Export API → Validator: formats · Exports validation and corrected-result outputs
- Autofix API → Static rules: applies · Autofix follows deterministic rule-fix logic
- Vite app → Home: routes to · Shell renders the upload and inspection page
- Vite app → Reconcile: routes to · Shell renders the reconciliation workflow page
- Vite app → Batch: routes to · Shell renders batch processing views
- Vite app → Claims: routes to · Shell renders claim-centric review views
- Vite app → UI panels: composes · Shell composes shared UI building blocks
- Home → UI store: reads/writes · Home page uses shared state for file and result handling
- Reconcile → UI store: reads/writes · Reconciliation page uses shared state for matched results
- Batch → UI store: reads/writes · Batch page uses shared state for multi-file workflows
- Claims → UI store: reads/writes · Claims page uses shared state for inspection data
- Python runtime → FastAPI app: supports · Defines the backend runtime and dependencies
- Hosting config → FastAPI app: deploys · Supports backend hosting configuration