# MediLink Gmail Orchestrator

This folder contains the repo-run Python 3.11+ cloud ingestion and orchestration path for MediCafe. It is the maintained cloud runtime for Gmail notification handling, attachment intake, queueing, preprocessor validation, and related operational controls.

This code is intentionally separate from the packaged `medicafe` local/XP workflow path described in `setup.py`.

## What Lives Here

| Path | Role |
| --- | --- |
| `main.py` | Cloud Run / HTTP entrypoint |
| `api.py` | API and admin routes |
| `auth.py` | Gmail and auth-mode helpers |
| `config.py` | runtime configuration loading |
| `services.py` | service wiring and client selection |
| `processor.py` | downstream attachment and queue processing |
| `preprocessor.py` | metadata/file validation before queue write |
| `preprocessor_gate.py` | promotion gate logic for shadow versus enforce behavior |
| `watch.py` | Gmail watch management |
| `cleanup.py` | cleanup helpers |
| `setup_flow.py`, `setup_runtime.py`, `setup_alerting.py`, `setup_common.py`, `setup_evidence.py` | setup, remediation, and operational support |
| `validate_and_complete_setup.py` | canonical operator entrypoint for setup/verification |
| `verify_syntax.py` | syntax verification helper |
| `tests/` | cloud-specific regression coverage |

## Canonical Operator Path

Use the validator-first workflow:

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

Useful variants:

```powershell
py -3.11 cloud/orchestrator/validate_and_complete_setup.py --validate-only
py -3.11 cloud/orchestrator/validate_and_complete_setup.py --verify-runtime
py -3.11 cloud/orchestrator/setup_alerting.py --project-id <PROJECT_ID> --check-drift
```

Prefer this path over older ad hoc deployment scripts so Cloud Run, watch management, auth posture, preprocessor state, and alerting stay aligned.

## Current Runtime Concerns

The orchestrator currently includes first-class support for:

- Gmail watch setup and refresh
- Pub/Sub push intake
- queue writes and downstream processing
- auth-mode handling for runtime and setup contexts
- preprocessor shadow/enforce behavior and promotion gate checks
- admin/backfill/operational support flows
- alerting and verification support

For current operational posture and procedures, use the runbooks and architecture docs rather than relying on historical deployment notes alone.

**Theme 1 (operational confidence) ??agent note:** `--validate-only` / `--ops-confidence` do not replace a GCP **smoke drill** or stored evidence. What counts as ??one??vs still open: `docs/reports/ACTIVE_FINDINGS_SUMMARY_2026_Q1.md` (Theme 1 handoff) and `docs/runbooks/MediLink_Gmail_Orchestrator_Operations.md` (closure checklist).

## Local Development and Verification

Basic import sanity check:

```powershell
py -3.11 -c "import cloud.orchestrator.main as m; print('ok')"
```

Run cloud tests:

```powershell
py -3.11 -m unittest discover -s cloud/orchestrator/tests
```

Syntax verification:

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

## Configuration

Cloud configuration is defined through:

- `config.py`
- environment variables
- validator/setup scripts

Important config areas include project identity, mailbox identity, storage, auth mode, machine routing, attachment filters, admin secrets, and preprocessor behavior.

Keep deployment-specific values out of long-lived docs when possible. Document the configuration model and use the validator/runbooks for environment-specific setup.

## Related Docs

- `docs/MEDILINK_CLOUD_MIGRATION.md`
- `docs/architecture/MediLink_Gmail_GCP_Implementation.md`
- `docs/runbooks/MediLink_Gmail_Orchestrator_Operations.md`
- `docs/runbooks/Cloud_Readiness_Cloud_Degraded_Validation.md`

## Scope Boundary

This folder is the maintained cloud runtime. It is not:

- the packaged local `medicafe` CLI path
- the legacy GAS baseline rebuild path in `MediLink/gcp_baseline/`
- the full migration/validation reporting surface in `scripts/unified_model/`

