How vitthalhumbe/ciphercrew-claimcraft works
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: app.py FastAPI app · App.jsx Vite app · parse.py Parse API · validator.py Validator
Components 25
Backend
FastAPI service for parsing, validation, reconciliation, and AI-assisted analysis
- FastAPI app · Backend application entry point that wires the API service together
backend/app.py - Parse API · HTTP boundary for parsing uploaded EDI
backend/routes/parse.py - Validate API · HTTP boundary for validation and reporting
backend/routes/validate.py - Reconcile API · HTTP boundary for 835-to-837 claim matching
backend/routes/reconcile.py - Chat API · AI explanation boundary for validation and file guidance
backend/routes/chat.py - Export API · Output boundary for JSON, CSV, and corrected EDI downloads
backend/routes/export.py - Autofix API · Deterministic remediation boundary for known issues
backend/routes/autofix.py - EDI core · Single-pass tokenizer and parser state machine for EDI segments
backend/edi_parser/core.py - 837 parser · Transaction-specific structural parser for 837 claims
backend/edi_parser/parsers/parser_837.py - 835 parser · Transaction-specific structural parser for 835 remittance data
backend/edi_parser/parsers/parser_835.py - 834 parser · Transaction-specific structural parser for 834 enrollment data
backend/edi_parser/parsers/parser_834.py - Validator · Coordinates static and live validation passes
backend/edi_parser/validator.py - Static rules · Offline HIPAA and structural rule enforcement
backend/edi_parser/validator_static.py - Live checks · Network-backed reference lookups and registry verification
backend/edi_parser/validator_live.py - HCPCS data · Embedded reference data loader for code validation
backend/edi_parser/hcpcs_loader.py - Groq layer · Backend integration area for hosted Llama explanations
backend/groq
Frontend
React/Vite UI for upload, inspection, batch processing, and reconciliation
- UI store · Shared client state for EDI workflows and results
frontend/src/store/useEdiStore.js - Home · Upload and inspection entry page
frontend/src/pages/Home.jsx - Reconcile · 835 and 837 matching workflow page
frontend/src/pages/Reconcile.jsx - Batch · Multi-file processing and review page
frontend/src/pages/Batch.jsx - Claims · Claim-centric inspection and review page
frontend/src/pages/Claims.jsx - UI panels · Shared viewers, tables, modals, and navigation components
frontend/src/components - Vite app · React application shell and client bootstrap
frontend/src/App.jsx
Deployment
Runtime and hosting configuration for split deployment
- Python runtime · Backend runtime and dependency definition
backend/requirements.txt - Hosting config · Split deployment configuration for backend and frontend hosting
backend/railway.toml
Connections 30
- 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