# Velocity Local Dev Snapshot

This document defines the correct way to work against a local copy of the current Velocity backend state without polluting Git and without guessing whether a backend-only change will work in production.

## Why This Exists

Project Velocity now depends on live PostgreSQL-backed surfaces and runtime state that cannot be validated reliably from frontend-only local development.

Examples:

- operator identity and profile hydration
- CRM-backed Sentinel client selection
- Oracle Canvas data access and sharing
- verified team-account lists for share flows

The correct solution is a repeatable local snapshot workflow.

## Design Rule

Local runtime copies must never be committed.

Everything produced by this workflow lives under gitignored paths:

- `.local-dev/`
- `runtime-snapshots/`
- `local-dev-bundles/`

## Bundle Shape

The Linux-origin export bundle contains:

- `backend.env.export`
- `velocity.dump`
- `restore.instructions.txt`

This is intentionally minimal. It gives local developers what they need to stand up a local database-backed verification surface without pushing runtime state into the repository.

## Export From Linux Box

Run this on the Linux-origin host:

```bash
cd /opt/desineuron-velocity-site/repo
bash scripts/export_velocity_local_bundle.sh
```

This creates a tarball in `/tmp` named like:

```text
/tmp/velocity-local-bundle-YYYYmmdd-HHMMSS.tar.gz
```

## Import On Windows Dev Machine

1. Copy the tarball to the Windows machine.
2. Extract it under:

```text
Project_Velocity/.local-dev/source-bundles/<bundle-name>/
```

3. Run:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\import_velocity_local_bundle.ps1
```

This will:

- copy the exported env snapshot into `.local-dev/backend/.env.local`
- copy the PostgreSQL dump into `.local-dev/db/velocity.dump`
- generate a local Docker Compose file for PostgreSQL
- generate a restore script

## Restore Local Database

After import, run:

```powershell
powershell -ExecutionPolicy Bypass -File .\.local-dev\db\restore_local_snapshot.ps1
```

This restores the dump into a local PostgreSQL container on:

- host: `127.0.0.1`
- port: `54329`
- db: `velocity_local`
- user: `velocity_local`
- password: `velocity_local`

## Local Backend Wiring

The backend expects these env keys:

- `VELOCITY_DB_HOST`
- `VELOCITY_DB_PORT`
- `VELOCITY_DB_NAME`
- `VELOCITY_DB_USER`
- `VELOCITY_DB_PASSWORD`
- `DATABASE_URL`
- `CORS_ORIGINS`
- `VELOCITY_ASSET_DIR`
- `JWT_SECRET_KEY`

The exported env snapshot provides the production-shaped variable names. For local verification, point the DB values to the local PostgreSQL container rather than the production database.

## Create A Zip For Sayan And Sourik

Once `.local-dev/` is hydrated locally, run:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\package_velocity_local_bundle.ps1
```

This creates a gitignored zip under:

```text
Project_Velocity/local-dev-bundles/
```

That zip is the correct handoff artifact for teammate local verification.

## What This Solves

This workflow allows local verification of:

- real account-backed login flows
- profile name/avatar hydration
- share-recipient lookup
- Sentinel CRM client selection
- Oracle-backed DB reads

## What It Does Not Solve By Itself

This does not automatically fix backend bugs.

If Oracle still returns `500` locally after restoring the snapshot, that is now a real reproducible backend issue rather than a blind production-only guess.

## Current Constraint

The current machine cannot SSH into the Linux box because the host is configured for publickey auth and this workstation is not authorized yet.

That means the export step must currently be triggered from a machine or shell that already has valid SSH/key access to the Linux-origin host.