Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
111 lines (69 loc) · 3.79 KB

MIGRATION_GUIDE.md

File metadata and controls

111 lines (69 loc) · 3.79 KB
Raw

Migration methodology

End-to-end process for moving an Excel/VBA workbook to a Python web app using the Strangler Fig pattern: build feature by feature; keep Excel available until the web app is validated.

Repository map: PROJECT_LAYOUT.md · VBA → Python: VBA_REFERENCE.md

Primary deliverable: specs/<workbook>_LOGIC_ANALYSIS.md — business meaning linked to sheets, formulas, and VBA.

Phase 1 — Extraction

Produce a structured JSON inventory (sheets, formulas, VBA, validations, named ranges).

pip install -r requirements.txt
python scripts/extract.py path/to/workbook.xlsm -o extractions/<name>_extraction.json

Output: extractions/<name>_extraction.json (gitignored; regeneratable from the workbook).

Or use the web app step 1 — upload triggers the same extraction in the browser session.

Phase 2 — Logic analysis

Transform JSON + owner context into a validated logic analysis.

Path How
Web Steps 1–3 at http://localhost:8501 → download .md from /review
CLI python scripts/generate_logic_agent.py extractions/<name>_extraction.json → complete in Cursor with @specs/<name>_LOGIC_AGENT_PROMPT.md

Optional later: functional spec via generate_spec_agent.py or generate_spec.py (LLM).

Business validation: owner reviews the logic analysis, marks features validated / changed / removed, then development starts.

Phase 3 — Prioritization

Before coding, rank validated features. Copy this table into a workbook-specific file (e.g. specs/<name>_MIGRATION_PLAN.md) or a project issue:

ID Feature Criticality Frequency Complexity Priority Status
F01 … Blocking Daily Low 1 ⬜

Criticality: Blocking / Useful / Secondary
Frequency: Daily / Weekly / Occasional
Complexity: Low (< 2 h) / Medium (2–8 h) / High (> 8 h)
Status: ⬜ To do · 🔄 In progress · ✅ Validated · ❌ Dropped

Start with Blocking + Daily + Low complexity.

Phase 4 — Architecture

This repo targets FastAPI + static HTML (web/server.py) for the migration UI and future product surface. Migrated logic lives in src/ (f01_*, …); tests in tests/.

Role Library
Excel I/O openpyxl, oletools
Web FastAPI, uvicorn
Data pandas
Charts Plotly
Tests pytest

Legacy Streamlit (web/app.py) remains for reference only.

Phase 5 — Iterative coding

One feature per cycle from the prioritization grid.

  1. Migrate VBA from extractions/<name>_extraction.json → src/fXX_<name>.py (VBA_REFERENCE.md)
  2. Add tests/test_fXX.py using expected values from the logic analysis
  3. pytest tests/test_fXX.py -v
  4. Branch → PR → business validation

Cursor prompt example:

@workspace Migrate feature F02 from extractions/<name>_extraction.json to src/f02_*.py.
Use VBA_REFERENCE.md. Match business logic from specs/<name>_LOGIC_ANALYSIS.md.

Phase 6 — Web interface

Wire validated src/ modules into the FastAPI app (new routes or pages under web/). Reproduce legacy inputs, results, and navigation from the logic analysis.

Phase 7 — Deployment

docker build -t excel-migration .
docker run -p 8501:8501 excel-migration

Production: Docker on an internal server, Azure Container Apps, or Compose with PostgreSQL if persistence is required.

Phase 8 — Decommission Excel

When all prioritized features are validated, users have run the web app daily for 2–4 weeks, and no blocking bugs remain for 2 weeks — retire the .xlsm as the primary tool. Keep extractions/ snapshots and specs/ as permanent reference.