# MediCafe

MediCafe is a mixed local/cloud healthcare workflow automation repository. It combines legacy clinic-side workflows (`MediBot`, `MediLink`, and `xp_client`) with shared package utilities in `MediCafe` and a newer Gmail ingestion/orchestration path in `cloud/orchestrator`.

This repository intentionally supports more than one runtime model. It is not a single deployable app with one entrypoint.

## Runtime Tracks

| Track | Primary code | Python | Primary use |
| --- | --- | --- | --- |
| Local / XP-compatible workflow | `MediCafe`, `MediBot`, `MediLink`, `xp_client` | 3.4.4-compatible package path | Clinic-side claims, eligibility, deductible, reconciliation, download, and Medisoft-oriented automation |
| Cloud / orchestrator workflow | `cloud/orchestrator`, `tools`, `docs/runbooks` | 3.11+ repo-run path | Gmail ingestion, queueing, preprocessor validation, alerting, setup, and runtime operations |
| Shared migration / validation tooling | `MediCafe`, `scripts/unified_model`, `sql`, `tests` | Mixed | Shadow-pipeline, cloud-readiness, schema, validation, and reporting support |

`setup.py` packages the local/XP-compatible path. The cloud orchestrator is maintained as repo-run code.

## Primary Entry Points

Package CLI:

```bash
medicafe launcher
python -m MediCafe launcher
```

Current package commands exposed by `MediCafe/__main__.py`:

- `medicafe launcher`
- `medicafe medibot [config_file]`
- `medicafe medilink`
- `medicafe claims_status`
- `medicafe deductible`
- `medicafe download_emails`
- `medicafe cloud_daemon [config_file]`
- `medicafe send_error_report`
- `medicafe send_queued_error_reports`
- `medicafe docx_index_rebuild`
- `medicafe preflight`
- `medicafe reconcile`
- `medicafe version`

Canonical cloud operator path:

```powershell
py -3.11 cloud/orchestrator/validate_and_complete_setup.py
```

## Repository Map

- `MediCafe/`: shared package, CLI entrypoint, launcher, preflight, cloud-readiness helpers, API utilities, reconciliation, error reporting, and shared runtime helpers
- `MediBot/`: Medisoft-oriented local preprocessing and data-entry support scripts
- `MediLink/`: claims, eligibility, deductible, remittance, Gmail helper, and Apps Script-related assets
- `cloud/orchestrator/`: Cloud Run service, auth/config/runtime helpers, preprocessor gate, watch/admin flows, setup scripts, and cloud tests
- `xp_client/`: XP-side cloud queue consumer (`medilink_cloud_daemon.py`)
- `tests/`: main regression suite for package/local workflows, API helpers, launcher behavior, preflight, cloud-readiness, and integration coverage
- `scripts/unified_model/`: shadow-pipeline and unified relational validation tooling
- `sql/`: SQL artifacts used by migration and validation work
- `docs/`: maintained documentation surface
- `tools/`: operator and build helpers that are outside the packaged runtime

The workspace root also contains operational inputs, artifacts, and generated state such as `input/`, `TEST_CLAIMS/`, `ERA_TEST_DUMP/`, `reports_queue/`, `archive/`, `build/`, `dist/`, `.pytest_cache/`, and `tmp*`. Do not treat those folders as the canonical source layout.

## Configuration

Primary local configuration files:

- `json/config.json`
- `json/crosswalk.json`
- `json/medisoftconfig.json`

Cloud/orchestrator runtime settings are managed through `cloud/orchestrator/config.py`, environment variables, and the validator/setup flow.

## Testing

Main test surfaces:

- `tests/`
- `cloud/orchestrator/tests/`

Canonical automated test entrypoint:

```bash
python3 -m pytest -v
```

Windows equivalent:

```powershell
py -3.11 -m pytest -v
```

`pytest.ini` collects both test surfaces and excludes the current duplicate-name conflicts plus the known `api_factory` pytest-incompatible file. For focused runs:

```bash
python3 -m pytest -q tests/test_preflight.py
python3 -m pytest -q tests/test_config_loader_diagnostics.py
python3 -m pytest -q tests/test_error_reporter_configloader_degraded.py
python3 -m pytest -q tests/test_launcher_next_step_orchestration.py
python3 -m pytest -q tests/test_cloud_readiness_health.py
python3 -m pytest -q tests/test_bundle_build_telemetry.py
python3 -m pytest -q cloud/orchestrator/tests
```

See `docs/TESTING_GUIDE.md` for the current suite shape, default excludes, and standalone script-style harnesses that are not part of the canonical pytest run.

## Documentation

Start here:

- `docs/README.md`
- `docs/MEDICAFE_MASTER_GUIDE.md`
- `docs/TESTING_GUIDE.md`
- `docs/MEDICAFE_API_ARCHITECTURE.md`
- `docs/MEDILINK_CLOUD_MIGRATION.md`
- `cloud/orchestrator/README.md`

## Security and Repo Hygiene

- Avoid PHI in logs, reports, and committed artifacts.
- Use `send_error_report` and `send_queued_error_reports` for diagnostics instead of ad hoc data exports.
- Treat tokens, certificates, raw client secrets, build outputs, and downloaded artifacts as operational state, not documentation or source of truth.

## License

MIT License. See `LICENSE`.
