claudetools/clients/valleywide/app-modernization/docs/MODERNIZATION_ROADMAP.md

# Valley Wide ORDERS Modernization Roadmap

This document tracks the phased modernization of Valley Wide Plastering's VB6 ORDERS application to a modern web-based ERP. The strategy uses parallel development with SQL Server as the common backend, allowing VB6 and web clients to coexist during transition.

## Legend
- [ ] Not started
- [~] In planning
- [x] Completed
- Priority: P1 (critical/blocking), P2 (important), P3 (nice-to-have)

---

## Strategic Approach

**End Goal:** Modern web application replacing VB6 desktop client

**Migration Strategy:** Dual-client parallel development with gradual user adoption
- SQL Server backend supports both VB6 and web clients simultaneously
- VB6 continues production use while web client is developed
- Users transition module-by-module based on beta testing
- Zero-downtime migration with easy rollback per module

**Timeline:** 8-9 months to full production rollout

---

## Phase 1: Foundation & Database Migration (Month 1)

**Priority:** P1 (CRITICAL - removes 2GB Jet limit, enables all future work)

### Infrastructure Setup

- [ ] **DEV-001:** Provision development server environment
  - **Options:** Repurpose SERVER3, cloud VM, or dedicated workstation
  - **Requirements:** VB6 SP6 + OCX dependencies, SQL Server DEV instance
  - **Status:** Not started
  - **Blocking:** All development work

- [ ] **DEV-002:** Stand up VB6 build environment
  - **Components needed:**
    - Windows 10/11 VM with VB6 SP6 Enterprise
    - True DBGrid Pro 7.0 (`todg7.ocx`)
    - FarPoint Spread (`Flp32a30.ocx`)
    - Crystal Reports 7 runtime (`Crystl32.OCX`, `craxdrt.dll`)
    - MS common controls (TABCTL32, MSCOMCTL, MSCOMCT2, comdlg32)
    - EasyP.ocx
  - **Purpose:** Verify source compiles, understand business logic, test against SQL
  - **Status:** Not started

- [ ] **DEV-003:** Stand up SQL Server development instance
  - **Environment:** Separate from production
  - **Version:** SQL Server 2022 or Azure SQL Database
  - **Status:** Not started

### Database Migration (Week 1-2)

- [ ] **DB-001:** Jet → SQL Server schema migration
  - **Tool:** SQL Server Migration Assistant (SSMA) for Access
  - **Scope:** All 130 tables
  - **Deliverable:** SQL Server schema with proper types, indexes, constraints
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **DB-002:** Data migration and validation
  - **Process:** SSMA data transfer
  - **Validation:** Record counts, key relationships, data integrity checks
  - **Document:** Type conversion issues and resolutions
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 2-3 days

- [ ] **DB-003:** Enable SQL Server row versioning
  - **Purpose:** Prevent VB6/web client conflicts during parallel operation
  - **Implementation:** Add `rowversion` columns to all tables
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 1 day

- [ ] **DB-004:** Create development database snapshot
  - **Purpose:** Reproducible dev environment, quick restore for testing
  - **Priority:** P2
  - **Status:** Not started

### VB6 SQL Server Adaptation (Week 2-3)

- [ ] **VB6-001:** Update `modADO.bas` for SQL Server
  - **Changes:** Connection strings (Jet → SQL Server)
  - **Convert:** Inline SQL to stored procedures (safer concurrency)
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 5-7 days

- [ ] **VB6-002:** Test VB6 against SQL Server (comprehensive)
  - **Scope:** All modules, especially Certified Payroll + Positive Pay
  - **Test data:** Production-like dataset
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 5-7 days

- [ ] **VB6-003:** VB6 compatibility with Windows 10/11
  - **Goal:** Remove Win7 VM dependency
  - **Test:** VB6 runtime + OCX registration on Win10/11
  - **Fallback:** Application compatibility shims or Windows Sandbox
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

### Production Deployment (Week 3-4)

- [ ] **DEPLOY-001:** Deploy SQL Server to production
  - **Prerequisites:** All testing complete, backup/restore procedures
  - **Cutover:** VB6 client switches from Jet to SQL Server
  - **Monitoring:** 2 weeks intensive observation
  - **Priority:** P1
  - **Status:** Not started
  - **Blocking:** Web client development

---

## Phase 2: Web Client Foundation & API Layer (Month 2)

**Priority:** P1 (enables all web development)

### Technology Stack Decision

- [ ] **TECH-001:** Choose web application framework
  - **Recommended:** Blazor Server/.NET 8
  - **Alternatives:** React + .NET API, ASP.NET Core MVC
  - **Factors:** Team skills, component libraries, VB6 logic porting ease
  - **Priority:** P1
  - **Status:** Not started
  - **Blocking:** All web development

### API Layer Development

- [ ] **API-001:** Build REST API on SQL Server database
  - **Framework:** .NET 8 Web API
  - **Scope:** CRUD operations for all 130 tables
  - **Authentication:** OAuth/JWT
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 2-3 weeks

- [ ] **API-002:** Port business logic from VB6 `modADO.bas`
  - **Scope:** Critical validation rules, calculations, workflows
  - **Testing:** Unit tests for all ported logic
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 2-3 weeks

- [ ] **API-003:** Implement Certified Payroll API endpoints
  - **Scope:** prevailing-wage calculations, report generation
  - **Testing:** Extensive testing (legal compliance requirement)
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **API-004:** Implement Positive Pay API endpoints
  - **Scope:** Bank file generation for CRD, SWI, VWP
  - **Testing:** Validate against bank specs
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 1 week

### Web Client Scaffolding

- [ ] **WEB-001:** Authentication and security framework
  - **Requirements:** User login, role-based access control
  - **Integration:** Match VB6 `tblSECURITY` user/role model
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **WEB-002:** Base UI framework
  - **Components:** Navigation, layout, theming
  - **Design:** Responsive (desktop + mobile)
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **WEB-003:** Audit logging system
  - **Purpose:** Track VB6 vs web client actions for debugging
  - **Implementation:** `AuditLog` table with client type tracking
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 2-3 days

---

## Phase 3: Web Client Beta - Read-Only Modules (Month 2-3)

**Priority:** P2 (high value, zero risk - read-only)

### Beta Module 1: Project Dashboard

- [ ] **MOD-001:** Project list view
  - **Data source:** `tblPROJECT`
  - **Features:** Search, filter, sort
  - **Beta users:** Project managers, office staff (3-5 people)
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-002:** Lot details view
  - **Data source:** `tblLOTINFO`, `tblPLANS`, `tblCHANGE`
  - **Features:** Lot status, plans, change orders
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-003:** Orders status view
  - **Data source:** `tblORDERS`, `tblTAKE`
  - **Features:** Order tracking, takeoff data
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-004:** Crew schedules view
  - **Data source:** `tblCREW`, `tblHRDAILY`
  - **Features:** Daily crew assignments, labor hours
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

### Beta Module 2: Reporting Portal

- [ ] **MOD-005:** Job cost reports
  - **Data source:** `tblJOBCOST`
  - **Replace:** Some of the 791 Crystal Reports
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **MOD-006:** AR/AP summary reports
  - **Data source:** `tblARMASTER`, `tblAPMASTER`
  - **Beta users:** Accounting, management
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-007:** Payroll reports
  - **Data source:** `tblPAYROLL`, `tblPAYHEADER`
  - **Features:** Period summaries, employee hours
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

---

## Phase 4: Web Client Beta - Light Data Entry (Month 3-4)

**Priority:** P2 (write capability, low-risk modules)

### Beta Module 3: Daily Labor/Crew Entry

- [ ] **MOD-008:** Daily hours entry (mobile-friendly)
  - **Data source:** `tblHRDAILY`
  - **Target users:** Crew foremen (5-10 people, field use)
  - **Features:** Enter hours, update crew assignments
  - **Device support:** Tablets, phones
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1-2 weeks

- [ ] **MOD-009:** Crew assignment management
  - **Data source:** `tblCREW`
  - **Features:** Assign crews to projects/lots
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

### Beta Module 4: Inventory Lookups/Updates

- [ ] **MOD-010:** Inventory level view
  - **Data source:** `tblINVTRY`, `tblINVPRICE`
  - **Target users:** Yard workers, purchasers (3-5 people)
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-011:** Inventory adjustments
  - **Features:** Simple quantity updates, notes
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-012:** Supplier lookups
  - **Data source:** `tblSUPPLIER`, `tblContractor`
  - **Priority:** P3
  - **Status:** Not started
  - **Effort:** 2-3 days

---

## Phase 5: Web Client - Complex Modules (Month 5-6)

**Priority:** P2 (complex business logic, needs thorough testing)

### Beta Module 5: Orders & Takeoffs

- [ ] **MOD-013:** Full order entry
  - **Data source:** `tblORDERS`, `tblTAKE`, `tblMEASURE`
  - **Target users:** Estimators (2-3 people initially)
  - **Features:** Complete order workflow, takeoff calculations
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 2-3 weeks

- [ ] **MOD-014:** Material estimates
  - **Business logic:** Port from VB6 calculation routines
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1-2 weeks

- [ ] **MOD-015:** Takeoff viewer
  - **Features:** View/edit takeoff measurements
  - **Grid component:** Blazor FlexGrid or equivalent
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1 week

### Additional Complex Modules

- [ ] **MOD-016:** Billing module
  - **Data source:** `tblBilling`, `tblMANBILL`
  - **Features:** Manual billing, billing status
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1-2 weeks

- [ ] **MOD-017:** Purchase Orders
  - **Data source:** `tblPOrder`, `tblPOMatrl`, `tblYardOrder`
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1-2 weeks

- [ ] **MOD-018:** Scaffold management
  - **Data source:** `tblScaffold`, `tblSC_Crew`, `tblScafPay`
  - **Priority:** P3
  - **Status:** Not started
  - **Effort:** 1 week

---

## Phase 6: Critical Compliance Modules (Month 7-8)

**Priority:** P1 (CRITICAL - legal/fraud-prevention requirements, must be perfect)

### Certified Payroll

- [ ] **MOD-019:** Certified payroll generation
  - **Data source:** `tblCERTIFIED`, `tblPAYROLL`, `tblPAYHEADER`
  - **Requirements:** Prevailing-wage calculations, government compliance
  - **Target users:** Payroll admin (1-2 people)
  - **Testing:** Extensive validation, parallel VB6 comparison
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 2-3 weeks

- [ ] **MOD-020:** Certified payroll reporting
  - **Format:** Government-required formats
  - **Validation:** Legal compliance verification
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 1 week

### Positive Pay (Bank Fraud Prevention)

- [ ] **MOD-021:** Positive Pay file generation (CRD bank)
  - **Data source:** `tblPosPayCRD`
  - **Format:** Bank-specific file format
  - **Testing:** Validate against bank specs
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-022:** Positive Pay file generation (SWI bank)
  - **Data source:** `tblPosPaySWI`
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **MOD-023:** Positive Pay file generation (VWP bank)
  - **Data source:** `tblPosPayVWP`
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 3-5 days

---

## Phase 7: Remaining Modules & Full Rollout (Month 8-9)

### Additional Modules

- [ ] **MOD-024:** AR/AP management
  - **Data source:** `tblARMASTER`, `tblAPMASTER`, related tables
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 2 weeks

- [ ] **MOD-025:** Repairs tracking
  - **Data source:** `tblREPAIR`, `tblRepList`
  - **Priority:** P3
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **MOD-026:** Materials/finishes management
  - **Modules:** Texture, Foam, Sand, BlackPaper
  - **Priority:** P3
  - **Status:** Not started
  - **Effort:** 1 week

### Production Readiness

- [ ] **PROD-001:** Performance optimization
  - **Scope:** Database indexes, query tuning, caching
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **PROD-002:** Security audit
  - **Scope:** Authentication, authorization, data protection
  - **Priority:** P1
  - **Status:** Not started
  - **Effort:** 3-5 days

- [ ] **PROD-003:** User training materials
  - **Deliverables:** Videos, documentation, quick-start guides
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **PROD-004:** Full user training
  - **Scope:** All users, all modules
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 2 weeks

- [ ] **PROD-005:** VB6 retirement
  - **Prerequisites:** All modules proven in production, zero critical issues
  - **Process:** Archive VB6, documentation handoff
  - **Priority:** P2
  - **Status:** Not started

---

## Technical Safeguards

### Concurrency Management

- [ ] **SAFE-001:** Row versioning implementation
  - **Purpose:** Prevent VB6/web overwrite conflicts
  - **Implementation:** `rowversion` columns on all tables
  - **Priority:** P1
  - **Status:** Not started

- [ ] **SAFE-002:** Optimistic concurrency checks
  - **Implementation:** Timestamp checks before updates
  - **Error handling:** User-friendly conflict resolution
  - **Priority:** P1
  - **Status:** Not started

- [ ] **SAFE-003:** Feature flags system
  - **Purpose:** Enable/disable web modules independently
  - **Use case:** Quick rollback if module has issues
  - **Priority:** P2
  - **Status:** Not started

### Monitoring & Metrics

- [ ] **MON-001:** Beta success metrics tracking
  - **Metrics:**
    - Adoption rate (% of target users using web)
    - Error rate (errors per session)
    - Concurrency conflicts (VB6/web collisions)
    - Performance (response times)
    - User satisfaction (surveys)
    - Data integrity (corruption checks)
  - **Expansion criteria:**
    - Error rate < 1% per session
    - Zero data integrity issues for 2 weeks
    - 80%+ user satisfaction
    - Concurrency conflicts < 0.1% of operations
  - **Priority:** P2
  - **Status:** Not started

---

## Research & Documentation

### Crystal Reports Migration

- [ ] **RESEARCH-001:** Inventory 791 Crystal Reports
  - **Goal:** Determine which reports are actively used
  - **Method:** Usage logging, user interviews
  - **Priority:** P2
  - **Status:** Not started
  - **Effort:** 1 week

- [ ] **RESEARCH-002:** Crystal Reports migration strategy
  - **Options:**
    - Crystal Reports for Visual Studio (auto-converts)
    - Modern reporting engine (SSRS, Power BI, custom)
  - **Decision factors:** Complexity, licensing, maintenance
  - **Priority:** P2
  - **Status:** Not started

### OCX/Component Migration

- [ ] **RESEARCH-003:** True DBGrid → .NET grid migration
  - **Target:** ComponentOne/MESCIUS FlexGrid
  - **Migration utility:** True DBGrid Pro 8.0 migration tool
  - **Priority:** P2
  - **Status:** Not started

- [ ] **RESEARCH-004:** FarPoint Spread → .NET migration
  - **Target:** Spread for WinForms
  - **Conversion:** `.ss2` designs to XML via GrapeCity designer
  - **Priority:** P2
  - **Status:** Not started

---

## Known Risks & Mitigation

### Risk 1: Undocumented Business Rules
**Impact:** HIGH
**Probability:** MEDIUM
**Mitigation:**
- Extensive beta testing with experienced users
- Parallel VB6/web operation during transition
- Module-by-module rollout (easy rollback)
- Preserve VB6 source as reference

### Risk 2: Certified Payroll Compliance Failure
**Impact:** CRITICAL (legal/contract violations)
**Probability:** LOW (with proper testing)
**Mitigation:**
- Extensive testing with parallel VB6 comparison
- Legal/compliance review before deployment
- Keep VB6 as backup for payroll until proven
- Gradual rollout to single payroll admin first

### Risk 3: Positive Pay Bank Integration Failure
**Impact:** HIGH (fraud prevention failure)
**Probability:** LOW (well-defined bank specs)
**Mitigation:**
- Validate output files against bank specifications
- Test with banks before production use
- Keep VB6 as backup until confirmed working
- Monitor first production files closely

### Risk 4: Performance Issues with Web Client
**Impact:** MEDIUM (user adoption)
**Probability:** MEDIUM
**Mitigation:**
- Performance testing during development
- Database indexing and query optimization
- Caching strategies
- Monitor response times during beta

### Risk 5: User Resistance to Change
**Impact:** MEDIUM (adoption rate)
**Probability:** MEDIUM
**Mitigation:**
- Early beta user involvement
- Comprehensive training
- Module-by-module adoption (users can stay on VB6)
- Highlight mobile/web benefits (field access)

---

## Success Criteria

### Phase 1 Success (Database Migration)
- [x] VB6 running against SQL Server in production
- [x] Zero data integrity issues
- [x] Performance equal or better than Jet
- [x] 2GB limit eliminated

### Beta Phase Success (Per Module)
- [x] Target beta users actively using module
- [x] Error rate < 1% per session
- [x] Zero concurrency conflicts with VB6
- [x] User satisfaction > 80%
- [x] No data corruption

### Production Rollout Success
- [x] All modules available in web client
- [x] Certified Payroll legal compliance verified
- [x] Positive Pay bank integration confirmed
- [x] User training complete
- [x] VB6 retired, web client primary

---

## Timeline Summary

| Phase | Duration | Key Deliverables |
|---|---|---|
| **Phase 1:** Foundation & DB Migration | Month 1 | SQL Server production, VB6 adapted |
| **Phase 2:** Web Foundation & API | Month 2 | API layer, web scaffolding |
| **Phase 3:** Read-Only Beta | Month 2-3 | Dashboards, reports (beta users) |
| **Phase 4:** Light Data Entry Beta | Month 3-4 | Labor entry, inventory (beta users) |
| **Phase 5:** Complex Modules | Month 5-6 | Orders, billing, purchasing |
| **Phase 6:** Critical Compliance | Month 7-8 | Certified Payroll, Positive Pay |
| **Phase 7:** Full Rollout | Month 8-9 | Training, VB6 retirement |

**Total Timeline:** 8-9 months from project start to VB6 retirement

---

## Notes

- **This is a living document** - update as features ship or requirements change
- **Checkboxes** track implementation status: [ ] planned, [~] in progress, [x] completed
- **Priority levels** guide sprint planning: P1 critical/blocking, P2 important, P3 nice-to-have
- **Effort estimates** are approximate; adjust based on actual experience
- **Dependencies** are noted in "Blocking" fields - resolve blockers first

---

**Last Updated:** 2026-06-14
**Status:** Initial roadmap created, planning phase
**Next Review:** After Phase 1 completion