ROADMAP.md

🗺️ CommerceRack b00t Rust Translation - Checkpoint Roadmap

Philosophy: Plan → Checkpoint → Validate → Backtrack if needed → Iterate

Checkpoint Strategy

Each checkpoint includes:

1. Plan: Clear objectives and acceptance criteria
2. Execute: Implement with tests
3. Validate: Run tests, verify functionality
4. Commit: git commit with descriptive message
5. Backtrack Option: Revert if validation fails

---

Phase 1: Foundation ✅ COMPLETE

Checkpoint 1.1: Repository Setup ✅

Commit: f52d6fa

• Analyze MySQL schema (152 tables)
• Analyze Perl codebase (318 modules)
• Create Postgres migration (22 tables)
• Set up Cargo workspace
• Implement database layer
• Validation: Schema loads, models compile
• Backtrack: None needed ✅

Checkpoint 1.2: Multi-Agent Infrastructure ✅

Commit: 6ec6524

• Create pm2 ecosystem (8 agents)
• Implement captain orchestrator
• Create specialist agent workers
• Set up OpenTofu k0s infrastructure
• Create deployment documentation
• Validation: Agents start, infrastructure provisions
• Backtrack: None needed ✅

---

Phase 2: Core Module Translation (NEXT)

Checkpoint 2.1: Customer Module Foundation

Branch: feature/customer-module Estimated: 1-2 days

Plan:

1. Create crates/customer/src/lib.rs
2. Define Customer struct with all fields from Perl
3. Implement basic CRUD operations with SQLx
4. Add unit tests for each operation
5. Create integration tests with testcontainers

Acceptance Criteria:

• Customer struct matches CUSTOMER.pm fields
• All CRUD operations work against Postgres
• Unit tests pass (>80% coverage)
• Integration tests pass with real DB

Validation Steps:

cargo test --package commercerack-customer
cargo clippy -- -D warnings
cargo build --release

Backtrack Plan: If tests fail or design issues found:

git reset --hard HEAD~1
# Review Perl implementation again
# Adjust Rust design
# Retry with new approach

Checkpoint 2.2: Customer Authentication

Branch: feature/customer-auth Depends on: Checkpoint 2.1

Plan:

1. Implement password hashing with argon2
2. Add salt generation per customer
3. Create authentication methods
4. Add session management
5. Write security tests

Acceptance Criteria:

• Passwords hashed with argon2id
• Unique salt per customer
• Login/logout methods work
• Session tokens generated (JWT ready)
• Security audit passes

Validation Steps:

cargo test customer::auth
# Run security agent analysis
pm2 trigger security-agent analyze

Backtrack Plan:

git reset --soft HEAD~1
# Review security recommendations
# Adjust crypto implementation

Checkpoint 2.3: Customer Address Management

Branch: feature/customer-addresses Depends on: Checkpoint 2.1

Plan:

1. Create CustomerAddress model
2. Implement address CRUD
3. Add address type enum (SHIP, BILL, etc.)
4. Link to customer records
5. Test multi-address scenarios

Acceptance Criteria:

• Address model complete
• Multiple addresses per customer
• Address types properly validated
• Tests cover edge cases

Validation Steps:

cargo test customer::address

---

Phase 3: Product & Inventory

Checkpoint 3.1: Product Catalog

Branch: feature/product-catalog Estimated: 2-3 days

Plan:

1. Create crates/product/
2. Translate PRODUCT.pm to Rust
3. Implement YAML/JSON serialization
4. Add product options (POGs)
5. Create comprehensive tests

Acceptance Criteria:

• Product struct complete
• YAML data fields work
• Options/variations supported
• Tests pass

Validation Steps:

cargo test --package commercerack-product
# Test with sample product data from Perl

Backtrack Plan:

git stash
# Re-examine Perl POG structure
# Redesign Rust approach
git stash pop

Checkpoint 3.2: SKU Lookup System

Branch: feature/sku-lookup Depends on: Checkpoint 3.1

Plan:

1. Implement SkuLookup model (60+ fields!)
2. Add inventory tracking
3. Amazon integration fields
4. Repricing strategy support
5. Performance tests

Acceptance Criteria:

• All 60+ SKU fields mapped
• Inventory quantities tracked
• Indexes perform well
• Bulk operations efficient

Validation Steps:

cargo test sku::lookup
# Benchmark bulk operations
cargo bench

---

Phase 4: API Layer

Checkpoint 4.1: Axum Server Skeleton

Branch: feature/axum-api Estimated: 1 day

Plan:

1. Create jsonapi/ binary crate
2. Set up Axum router
3. Add middleware (logging, CORS, auth)
4. Create health check endpoint
5. Docker build test

Acceptance Criteria:

• Server starts on port 8000
• Health check responds
• Middleware chain works
• Docker build succeeds

Validation Steps:

cargo run --bin jsonapi
curl http://localhost:8000/health
docker build -t commercerack-rust .

Backtrack Plan:

git reset HEAD~1
# Review Axum patterns
# Simplify middleware setup

Checkpoint 4.2: Customer API Endpoints

Branch: feature/api-customers Depends on: Checkpoints 2.1, 4.1

Plan:

1. Add /v1/customers routes
2. Implement GET, POST, PUT, DELETE
3. Add request validation
4. Create response DTOs
5. Integration tests

Acceptance Criteria:

• All CRUD endpoints work
• Validation rejects bad input
• Error handling consistent
• Integration tests pass

Validation Steps:

cargo test api::customers
# Manual API testing
curl -X POST http://localhost:8000/v1/customers \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'

---

Phase 5: Cart & Checkout

Checkpoint 5.1: Cart Data Model

Branch: feature/cart-model Estimated: 3-4 days (complex!)

Plan:

1. Create crates/cart/
2. Translate CART2.pm structure (12,630 LOC 😱)
3. Break into sub-modules:
   • cart/items
   • cart/pricing
   • cart/shipping
   • cart/tax
4. Progressive implementation
5. Extensive tests

Acceptance Criteria:

• Cart struct complete
• Item management works
• Sub-modules well organized
• Unit tests >70% coverage

Validation Steps:

cargo test --package commercerack-cart
# Test with Perl test cases

Backtrack Plan:

# If cart design too complex
git reset --hard feature/cart-model~1
# Simplify: MVP first, features later
# Restart with minimal cart

Checkpoint 5.2: Cart Calculations

Branch: feature/cart-calculations Depends on: Checkpoint 5.1

Plan:

1. Implement subtotal calculation
2. Add tax calculation
3. Shipping cost integration
4. Discount/promo codes
5. Performance benchmarks

Acceptance Criteria:

• Calculations match Perl results
• Performance <50ms for typical cart
• Edge cases handled
• Benchmarks documented

Validation Steps:

cargo test cart::calculations
cargo bench --bench cart_perf
# Compare with Perl baseline

---

Phase 6: Payment Integration

Checkpoint 6.1: Payment Gateway Trait

Branch: feature/payment-trait Estimated: 1 day

Plan:

1. Create crates/payment/
2. Define PaymentGateway trait
3. Add common error types
4. Create mock implementation
5. Design auth/capture/refund flow

Acceptance Criteria:

• Trait well-defined
• Mock gateway works
• Error handling complete
• Tests pass

Validation Steps:

cargo test payment::mock

Checkpoint 6.2: Authorize.Net Integration

Branch: feature/authorizenet Depends on: Checkpoint 6.1

Plan:

1. Implement AuthorizeNet gateway
2. Add API client (reqwest)
3. Transaction creation
4. Refund/void operations
5. Integration tests (sandbox)

Acceptance Criteria:

• API client works
• Charge succeeds (sandbox)
• Refunds work
• Tests use sandbox credentials

Validation Steps:

cargo test payment::authorizenet
# Sandbox integration test
AUTHNET_SANDBOX=true cargo test --test integration

Backtrack Plan:

git checkout feature/payment-trait
# Adjust trait if needed
# Restart gateway implementation

---

Phase 7: Database Completion

Checkpoint 7.1: Marketplace Tables (eBay)

Branch: feature/ebay-schema Estimated: 1 day

Plan:

1. Create migrations/002_ebay_tables.sql
2. Migrate 9 eBay tables
3. Convert ENUMs, fix dates
4. Add indexes
5. Test migration

Acceptance Criteria:

• All 9 eBay tables created
• Migration runs cleanly
• Indexes present
• Rollback works

Validation Steps:

psql commercerack < migrations/002_ebay_tables.sql
psql commercerack -c "\dt ebay*"
# Test rollback
psql commercerack < migrations/002_ebay_tables_down.sql

Backtrack Plan:

# If migration fails
psql commercerack < migrations/002_ebay_tables_down.sql
# Fix issues
# Re-apply

Checkpoint 7.2: Remaining Tables (130 total)

Iterative: Break into 10-15 table batches Estimated: 1 week

Plan: Create migrations 003-010 for remaining tables:

• 003: Supplier tables (6 tables)
• 004: Shipping tables (8 tables)
• 005: Warehouse tables (3 tables)
• 006: Marketing tables (10 tables)
• 007: Google/Sears marketplaces (5 tables)
• 008: Reporting tables (15 tables)
• 009: Miscellaneous infrastructure (20 tables)
• 010: Legacy/archive tables (remaining)

Per-migration Validation:

psql commercerack < migrations/00X_*.sql
psql commercerack -c "\dt" | wc -l  # Table count
# Rollback test
psql commercerack < migrations/00X_*_down.sql

---

Checkpoint Best Practices

Before Each Checkpoint

# 1. Create feature branch
git checkout -b feature/checkpoint-name

# 2. Plan in detail (write acceptance criteria)
# 3. Write tests FIRST (TDD)
# 4. Implement feature
# 5. Run validation

# 6. If validation PASSES:
git add .
git commit -m "Checkpoint: Feature name

Acceptance criteria:
- [x] Criterion 1
- [x] Criterion 2

Validation:
- cargo test passed
- benchmarks acceptable
- security audit clean
"

# 7. If validation FAILS:
git reset --hard HEAD  # Nuclear option
# OR
git reset --soft HEAD~1  # Keep changes, redo commit
# OR
git stash  # Save for later analysis
# OR
git revert HEAD  # Explicit undo commit

Validation Checklist Per Checkpoint

• cargo test passes (all crates)
• cargo clippy no warnings
• cargo build --release succeeds
• Integration tests pass
• Performance acceptable (if applicable)
• Security review (if applicable)
• Documentation updated

Recovery Commands

# View checkpoint history
git log --oneline --graph

# Return to specific checkpoint
git checkout <commit-hash>

# Create new branch from checkpoint
git checkout -b feature/new-approach <commit-hash>

# Compare checkpoints
git diff checkpoint-1 checkpoint-2

# Cherry-pick successful changes
git cherry-pick <commit-hash>

---

Current Status

Completed Checkpoints: 2

• ✅ 1.1: Repository Setup (f52d6fa)
• ✅ 1.2: Multi-Agent Infrastructure (6ec6524)

Next Checkpoint: 2.1 Customer Module Foundation Estimated Start: When infrastructure deployment validated Estimated Duration: 1-2 days

Branch Strategy:

main (protected)
  └── claude/perl-to-rust-b00t-01KhRNNMTqUTNuksyRwUnPW2 (current work)
        ├── feature/customer-module (next)
        ├── feature/customer-auth
        ├── feature/product-catalog
        └── ... (future features)

---

Success Metrics Per Phase

Phase	Checkpoints	Tests	Coverage	Performance
Phase 1	2/2 ✅	N/A	N/A	N/A
Phase 2	0/3	TBD	>80%	<100ms/op
Phase 3	0/2	TBD	>70%	<50ms/query
Phase 4	0/2	TBD	>80%	<200ms/req
Phase 5	0/2	TBD	>70%	<50ms/calc
Phase 6	0/2	TBD	>75%	<500ms/txn
Phase 7	0/2	N/A	N/A	N/A

---

Emergency Backtrack Scenarios

Scenario 1: Design Fundamentally Flawed

# Return to last known good checkpoint
git reset --hard <last-good-commit>
# Re-analyze Perl implementation
# Create new design document
# Start fresh feature branch

Scenario 2: Performance Unacceptable

# Keep implementation but benchmark
git stash
# Profile and identify bottleneck
# Optimize specific function
git stash pop
# Re-run benchmarks

Scenario 3: Tests Failing After Merge

# Bisect to find breaking commit
git bisect start
git bisect bad HEAD
git bisect good <last-known-good>
# Git will checkout commits to test
cargo test && git bisect good || git bisect bad
# Once found, analyze and fix

---

Roadmap Philosophy:

"Plan step-by-step, checkpoint frequently, validate rigorously, backtrack fearlessly." 🥾

Each checkpoint is a stable platform to either advance or retreat from. No work is wasted - even failed checkpoints teach us what NOT to do.