Project_Velocity/docs/LOCAL_DEV_SNAPSHOT.md

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:

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

This creates a tarball in /tmp named like:

/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:

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

3. Run:

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 -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 -ExecutionPolicy Bypass -File .\scripts\package_velocity_local_bundle.ps1

This creates a gitignored zip under:

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.