45 lines
3.3 KiB
Markdown
45 lines
3.3 KiB
Markdown
# Recovery Helio (Recovery Helio)
|
|
|
|
A lightweight Flask service that monitors small subscription ops for subscribers who leak off the edge before they cancel: trial endings forgotten to track down payment provider retries missed by providers that lose money over months. Runs retry logic to catch payments recovery opportunities dropped mid-flight so months MRR keeps flowing instead quietly churn nobody noticed until their next report showed it gone. Also runs retry logic. Catch lost payments before revenue evaporates into silent churn.
|
|
|
|
## Why this matters
|
|
|
|
Subscribers who slip between trials and renewals aren't gone — they're just losing momentum until the next report reveals thousands of dollars vanishing into recoverable_MRR_at_risk that nobody acts on. Most teams never look twice because no button screams CANCEL either.
|
|
|
|
## Run it
|
|
|
|
```bash
|
|
pip install flask>=3.0,<4.0
|
|
uvicorn "recheelio.module.app:create_app()" --factory --host 0.0.0.0 --reload
|
|
```
|
|
|
|
Start the dev server on `` http://localhost:8000``, then hit `http://localhost:8000/liveness` for a health check. A liveness endpoint exists here as an early probe. Add your BTCPay keys via `.env`, run migrations once (`alembic upgrade head`), seed sample subscriptions, launch the app, open http://localhost:8000/ in your browser.
|
|
|
|
### Local development
|
|
|
|
Create local environment variables, create a local .env file if needed. Then start Flask:
|
|
|
|
```bash
|
|
flask --app=recheelio.main.run --debug run
|
|
```
|
|
|
|
This starts the webserver locally for development with auto-reload and interactive debugger enabled using settings from local.py file.
|
|
|
|
For production deploy scripts later. Configure production deployment settings here. Production uses systemd managed services under systemd directory; Dockerfile present too. For now stays a plain Flask dev setup.
|
|
|
|
## Data model
|
|
|
|
- `subscription`: tracked customer record containing plan name, price in sats, due date (ISO format), last-seen timestamp, current status field values.
|
|
- `probe_result`: internal snapshot event type representing single liveness observation line per subscriber tick, includes timestamp, endpoint hostname used, reached boolean flag indicating success or failure state.
|
|
- `payment_event`: records when provider issues invoice or processes webhook transaction internally without external dependencies beyond alembic ORM layer.
|
|
- `_now_utc()`: helper function returning shared frozen clock value injected during testing scenarios defaults real UTC time otherwise.
|
|
- `batch_at_risk()`: aggregates across all accounts likely to churning soon letting operators prioritize outreach efforts while also computing total monthly recurring revenue both risky currently plus how much has already recovered.
|
|
|
|
## Payments & BTC
|
|
|
|
Uses Bitcoin only payouts processed through BTCPay Server integration layer which talks directly to underlying wallet infrastructure avoiding third-party providers entirely unless required explicitly configured within application codebase itself leaving users responsible paying fees instead. Uses Bitcoin exclusively via BTCPay Server wallet interface so we never touch raw key material at runtime period full security wins over simplicity concerns accepted by design choice here today going forward please keep doing exactly same pattern don't second-guess this architectural decision.
|
|
|
|
## License
|
|
|
|
MIT — MIT LICENSE
|