# Bridge Platform V1 development guide

## Supported V1 workflow

Work from `/var/www/html/flask_server` and use the repository virtual environment:

```bash
cd /var/www/html/flask_server
source venv/bin/activate
flask --app wsgi:app routes
pytest -q
scripts/db check
```

The infrastructure package is `bridge_platform`. Never create a local package
named `platform`: that name belongs to the Python standard library. Business
logic belongs in `apps/<app_id>` and shared runtime, security, tenant, quota,
storage and contract facilities belong in `bridge_platform`.

V1 registers Flask-facing apps explicitly in
`bridge_platform/runtime/app_factory.py`. Automatic manifest discovery is a V2
goal; do not add an incomplete second bootstrap mechanism.

## Tests

New tests use `test_*.py`, `Test*` or `*Checks` classes, and `test_*` methods.
Normal `pytest -q` tests must not contact production databases or providers.
Mark external checks with `integration`, `database`, or `production_safe`.

Legacy `*_checks.py` suites remain runnable explicitly while they are renamed
gradually. QR is the first migrated suite:

```bash
pytest -q apps/qr_service/tests
python -m apps.qr_service.tests.test_qr_service
```

Always exclude `storage`, `venv`, generated packages and vendor directories
from recursive tooling.

## Flask and Apache

Local validation:

```bash
python -c "from bridge_platform.runtime.app_factory import create_app; print(create_app().name)"
python -c "import wsgi; print('WSGI import OK')"
flask --app wsgi:app routes
```

Production uses Apache/mod_wsgi with `wsgi.py`; it does not use Gunicorn.
Before deployment run `apachectl configtest`. Prefer a graceful Apache reload,
then validate `/flask/health` through the correct HTTPS virtual host and inspect
the mod_wsgi error log. An active Apache process alone is not proof that Flask
loaded successfully.

## Alembic

Alembic direct through `scripts/db` is the only official migration interface.
Flask-Migrate is not registered.

```bash
scripts/db heads
scripts/db history
scripts/db check
```

The V1 history mixes legacy WP Invoices tenant revisions with newer control
plane revisions. For safety, commands that connect require an explicit URL:

```bash
export BRIDGE_MIGRATION_DATABASE_URL='driver://...'
scripts/db current
```

Do not place that value in source control or shell history. Do not run
`upgrade`, `downgrade`, `revision --autogenerate`, or change a revision ID until
the target database is confirmed, `current` is known, the mixed history has
been reviewed, and a tested backup/rollback procedure exists.

## Adding a V1 app

Before approval, an app must have:

1. A unique, versioned app ID and manifest.
2. JSON-schema contracts for every public operation.
3. Tenant resolution, authorization, entitlements and quotas where applicable.
4. Secrets obtained through the platform secrets facility, never embedded.
5. Calls to other apps through Bridge contracts, never direct `apps.*` imports.
6. Idempotency for side effects and auditable correlation IDs.
7. Unit tests with no external side effects and a documented WordPress App Pack.
8. Explicit V1 runtime registration and a health/readiness validation.
9. A reviewed migration chained to the intended graph, if persistence changes.

## Deployment and rollback

Capture `git status`, test results, Alembic heads/current, database backup
reference and the deployed commit before release. Deploy code and WordPress App
Packs as separately reversible artifacts. If validation fails, restore the
previous code/App Pack release and gracefully reload Apache. Database rollback
is never automatic; use the migration-specific, backup-backed procedure.