Tyler
cf9af8e1d9
Replaces the in-memory store with SQLite via SQLAlchemy 2.0; adds automatic 837P ↔ 835 reconciliation on every 835 parse; ships a manual /reconciliation page; extends the claim lifecycle to a 7-state model with reversal handling. Key decisions (locked from brainstorming): - SQLite at ~/.local/share/cyclone/cyclone.db, overridable via CYCLONE_DB_URL (Postgres escape hatch) - SQLAlchemy 2.0 sync ORM; PRAGMA user_version migration runner - Strict auto-match on patient_control_number (CLM01 == CLP01) within +/-7 days of service_date - 7-state claim model with reversal that sets Claim.state=REVERSED and preserves prior state on Match.prior_claim_state - Reconciliation triggered inside store.add() after ERA persist; fail-soft (logged + activity event, never blocks parse) - 3 new API endpoints; new /reconciliation page; same palette and aesthetic voice as sub-project 1 Spec is approved-section-by-section and self-reviewed.
Cyclone
A self-hosted EDI claims management suite for a single billing office. Parses 837P professional claims and 835 ERA remittances (X12 005010X222A1 and 005010X221A1), with a local-only FastAPI backend and a React UI for browsing, filtering, and inspecting the parsed data.
Local-only on purpose: binds to 127.0.0.1, no auth, no internet exposure.
Built for one operator, one machine, one trading partner (Colorado
Medicaid, currently).
Install
# Backend (Python 3.11+)
cd backend
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
# Frontend (Node 20+)
cd ..
npm install
Dev
Two terminals:
# Terminal 1 — backend
cd backend
.venv/bin/python -m cyclone serve
# (defaults to 127.0.0.1:8000; override with CYCLONE_PORT=...; reload with CYCLONE_RELOAD=1)
# Terminal 2 — frontend
npm run dev
# (Vite on http://localhost:5173)
Then open http://localhost:5173. Drop an .txt 837P or 835 file on the
Upload page; navigate to Claims, Remittances, Providers, or Activity to
see the parsed data.
The frontend reads its backend URL from VITE_API_BASE_URL (default
empty). Create a .env.local at the repo root with:
VITE_API_BASE_URL=http://127.0.0.1:8000
Without that, the UI falls back to its in-memory sample store via the
existing data adapter (parses are disabled).
Test
# Backend
cd backend && .venv/bin/pytest
# Frontend type-check + build
npm run typecheck
npm run build
# Frontend unit tests
npm test
Project layout
.
├── backend/
│ ├── src/cyclone/
│ │ ├── api.py # FastAPI app, GET + parse routes
│ │ ├── store.py # InMemoryStore, mappers
│ │ ├── __main__.py # `python -m cyclone serve`
│ │ ├── cli.py # click CLI
│ │ └── parsers/ # X12 tokenizer, models, validator, writers
│ └── tests/
│ ├── fixtures/ # co_medicaid_*.txt, minimal_*.txt
│ ├── test_api.py # parse-837/835 round-trip
│ ├── test_api_gets.py # 6 GET endpoints
│ ├── test_store.py # store + mappers + iterators
│ ├── test_api_streaming.py
│ └── test_api_parse_persists.py
├── src/ # React + Vite + TypeScript UI
│ ├── components/
│ │ └── ui/ # Skeleton, EmptyState, ErrorState, FilterChips, Pagination, …
│ ├── pages/ # Claims, Remittances, Providers, Activity, Upload
│ ├── hooks/ # useBatches, useClaims, useRemittances, useProviders, useActivity, useParse
│ ├── lib/ # api.ts (6 GET + parse837/parse835/health), format.ts, utils.ts
│ ├── store/ # zustand sample-data + parsed-batches store
│ └── types/ # shared TS types
├── docs/
│ ├── reference/ # condensed 837P/835/X12/CO Medicaid notes
│ └── superpowers/plans/ # implementation plan
├── tailwind.config.js # shimmer, scan, row-flash keyframes
└── package.json
Roadmap
This is sub-project 1 of 4. The other three are not in this build:
- Sub-project 2 — DB + reconciliation. Replace the in-memory store with SQLite/Postgres; add 837P ↔ 835 reconciliation matching payouts to original claims.
- Sub-project 3 — More 837P/835 features. Additional 837P validation rules (REF*G1 enforcement, BHT06), 835 CAS deep-parsing, 999 ACK, and 270/271 eligibility.
- Sub-project 4 — Frontend features. Per-claim detail drawer, batch diff view, real-time streaming of NDJSON GET responses, advanced filters (date range, multi-status, saved filter sets), keyboard-driven navigation.
License
No license file yet; this is internal-use software. Add a LICENSE file
when one is decided.