Tyler
120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend && .venv/bin/pytest
|
|
|
|
# Frontend type-check + build
|
|
npm run typecheck
|
|
npm run build
|
|
|
|
# Frontend unit tests (when added)
|
|
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.
|