romfast/roa2web-service-auto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2a101f1ef5093d9f7ef0d3b0a1cbb6e2fe5311e9
roa2web-service-auto/.auto-build/specs/unified-app/SUMMARY.md

10 KiB
Raw Blame History

Unified App Specification - Executive Summary

Created: 2025-12-22 Status: Implementation-Ready Estimated Effort: 2.5 days

What We're Building

A single unified SPA that consolidates the Reports App and Data Entry App into one application with:

  • Unified menu navigation between modules
  • Module isolation via error boundaries
  • Lazy loading for optimal performance
  • Single build and deployment process

Key Requirements (Top 5)

  1. Unified Navigation: Single menu with Reports and Data Entry sections
  2. Module Isolation: Error in one module doesn't crash the other
  3. Lazy Loading: Modules loaded on-demand, not upfront
  4. Simplified Deployment: Single IIS site instead of 2
  5. Zero Backend Changes: Both backends (8001, 8003) remain unchanged

Technical Approach

Architecture: Pragmatic Monolith

NOT using micro-frontends because:

  • Only 1 developer (not 20+ team)
  • Weekly deploys (not multiple times per day)
  • 1-5 concurrent users (not millions)
  • Same tech stack (Vue 3 only)

Using instead:

  • Error boundaries for isolation (50-70% blast radius reduction)
  • Lazy loading for performance
  • Feature flags for module control
  • Shared dependencies for smaller bundles

URL Structure

/login                     → Login
/                          → Redirect to /reports/dashboard

/reports/dashboard         → Dashboard
/reports/invoices          → Invoices
/reports/bank-cash         → Bank/Cash
/reports/trial-balance     → Trial Balance
/reports/telegram          → Telegram Bot
/reports/cache-stats       → Cache Stats

/data-entry                → Receipts List
/data-entry/create         → New Receipt
/data-entry/:id            → View Receipt
/data-entry/:id/edit       → Edit Receipt

API Routing

Vite Dev Proxy:

  • /api/reports/* → http://localhost:8001/api/*
  • /api/data-entry/* → http://localhost:8003/api/*
  • /uploads/* → http://localhost:8003/uploads/*

IIS Production Proxy:

  • Same routing via web.config URL rewrite rules

Critical Files (Top 10)

To Create (in root directory)

  1. package.json - Merged dependencies
  2. vite.config.js - Dual proxy + lazy loading
  3. src/main.js - App initialization
  4. src/App.vue - Root with unified menu
  5. src/router/index.js - Unified router
  6. src/config/menu.js - Menu configuration
  7. src/shared/components/ErrorBoundary.vue - Error isolation
  8. src/modules/reports/ReportsLayout.vue - Reports wrapper
  9. src/modules/data-entry/DataEntryLayout.vue - Data Entry wrapper
  10. web.config - IIS configuration

To Migrate

Reports Module (7 views, 5 stores, 1 service):

  • Views: Dashboard, Invoices, BankCash, TrialBalance, Telegram, CacheStats
  • Stores: dashboard, invoices, treasury, trialBalance, cacheStore
  • Service: api.js (change base URL to /api/reports/)

Data Entry Module (2 views, 3 components, 1 store, 1 service):

  • Views: ReceiptsList, ReceiptCreate
  • Components: OCRUploadZone, OCRPreview, OCRConfidenceIndicator
  • Store: receiptsStore
  • Service: api.js (change base URL to /api/data-entry/)

Shared (5 components, 3 stores):

  • Components: LoginView, AppHeader, SlideMenu, CompanySelector, PeriodSelector
  • Stores: auth, companies, accountingPeriod (factories)

CSS: Copy entire reports-app/frontend/src/assets/css/ structure

Implementation Phases

Phase 1: Setup (0.5 days)

  • Create directory structure
  • Setup package.json, vite.config.js
  • Copy shared components and CSS

Verify: npm install and npm run dev work

Phase 2: Migration (1 day)

  • Migrate all views, components, stores
  • Update API service base URLs
  • Merge CSS

Verify: All views render, no import errors

Phase 3: Routing & Navigation (0.5 days)

  • Create unified router with lazy loading
  • Create menu configuration
  • Create error boundaries
  • Integrate AppHeader and SlideMenu

Verify: Navigation works, lazy loading works

Phase 4: Error Boundaries & Resilience (0.25 days)

  • Test error isolation
  • Test feature flags
  • Add loading states

Verify: Error in one module doesn't crash other

Phase 5: Build & Deploy (0.25 days)

  • Production build
  • IIS configuration
  • Deploy to staging
  • Test all routes

Verify: Build succeeds, IIS works, APIs route correctly

Expected Build Output

dist/
├── index.html
├── assets/
│   ├── vendor-core.[hash].js        (~150KB) - Vue, Router, Pinia
│   ├── vendor-primevue.[hash].js    (~200KB) - PrimeVue components
│   ├── vendor-utils.[hash].js       (~80KB)  - Axios, date-fns
│   ├── vendor-charts.[hash].js      (~150KB) - Chart.js (lazy)
│   ├── vendor-export.[hash].js      (~200KB) - XLSX, jsPDF (lazy)
│   ├── reports.[hash].js            (~150KB) - Reports module (lazy)
│   ├── data-entry.[hash].js         (~100KB) - Data Entry module (lazy)
│   ├── main.[hash].js               (~50KB)  - App shell
│   └── main.[hash].css              (~80KB)  - Global CSS

Success Criteria

Must Have (Before Production)

  • All Reports views work correctly
  • All Data Entry views work correctly
  • Navigation preserves auth and company/period
  • Error in one module doesn't crash other
  • Single IIS site deployment works
  • API routing to both backends works

Performance Targets

  • Initial load < 2 seconds
  • Module switching < 500ms (cached)
  • Bundle size ≤ sum of current apps
  • Lighthouse score ≥ 90

Testing

  • E2E tests pass for login
  • E2E tests pass for Reports navigation
  • E2E tests pass for Data Entry navigation
  • E2E tests pass for module switching
  • E2E tests verify error isolation

Risks & Mitigations

Risk Mitigation
CSS conflicts Use design tokens, test thoroughly
Large bundle size Lazy loading, code splitting, tree shaking
Error boundary gaps Test error scenarios, add global handler
IIS deployment complexity Document config, test on staging first
Store contamination Module-scoped stores, test isolation

Rollback Plan

If deployment fails:

  1. Keep both apps running (zero downtime)

    • Leave /roa2web/ and /data-entry/ running
    • Add unified app at /unified/ for testing

  2. Quick rollback (15 minutes)

    • Restore IIS config from backup
    • Restore builds from dist-backup/

  3. Git rollback

    • Tag before merge: v1.0-pre-unified
    • Revert if needed: git reset --hard v1.0-pre-unified

Post-Implementation

After 1 Week of Stability

Archive old frontends:

mv reports-app/frontend reports-app/frontend-archived
mv data-entry-app/frontend data-entry-app/frontend-archived

Update documentation:

  • CLAUDE.md - Architecture and deployment
  • DEPLOYMENT_GUIDE.md - IIS configuration
  • README.md - Quick start and commands

Update scripts:

  • ./start-test.sh - Point to root directory
  • ./start-data-entry.sh - Point to root directory

Monitoring (First Month)

Week 1: Daily error log review Week 2-4: Performance optimization

  • Bundle size optimization
  • Further code splitting
  • Cache optimization

Open Questions & Recommendations

1. PrimeVue Theme

Question: Use saga-blue (reports-app) or lara-light-blue (data-entry-app)? Recommendation: saga-blue (reports-app is primary)

2. Feature Flags

Question: Config file or environment variables? Recommendation: Config file for simplicity, env vars for override

3. Module Activation

Question: All active by default or opt-in? Recommendation: All active by default (disable via config if needed)

4. Monitoring

Question: Console logs only or add Sentry/similar? Recommendation: Console logs for MVP, add monitoring later

Key Decisions Made

  1. Architecture: Pragmatic monolith (not micro-frontends)
  2. Error Isolation: Error boundaries per module
  3. Code Splitting: Lazy loading with manual chunks
  4. URL Structure: /reports/* and /data-entry/*
  5. API Routing: Proxy via Vite (dev) and IIS (prod)
  6. CSS System: Use reports-app CSS structure
  7. PrimeVue Theme: saga-blue (from reports-app)
  8. Shared Components: Use existing from shared/frontend/
  9. Deployment: Single IIS site at root /
  10. Backends: No changes (remain at 8001, 8003)

Documentation Locations

Complete Spec: .auto-build-data/specs/unified-app/spec.md Critical Files: .auto-build-data/specs/unified-app/critical-files.md This Summary: .auto-build-data/specs/unified-app/SUMMARY.md

Note: All implementation files will be created in the project root directory (. or /mnt/e/proiecte/roa2web/)

Reference Docs:

  • IMPLEMENTATION_PLAN_UNIFIED_APP.md - Original plan
  • CLAUDE.md - Project documentation (update after)
  • docs/ONBOARDING_CSS.md - CSS system guide
  • docs/CSS_PATTERNS.md - Available CSS patterns

Next Steps

  1. Read the complete spec: spec.md (detailed technical specification)
  2. Review critical files: critical-files.md (files to migrate/create)
  3. Start Phase 1: Project setup (0.5 days)
  4. Follow implementation plan: 5 phases over 2.5 days
  5. Test thoroughly: E2E tests before production
  6. Deploy to staging: Test IIS configuration
  7. Deploy to production: Single site deployment
  8. Monitor for 1 week: Daily error log review
  9. Archive old apps: After stability confirmed
  10. Update docs: Complete documentation updates

Quick Stats

  • Files to create: ~15
  • Files to migrate: ~20
  • CSS files to copy: ~30
  • Total files affected: ~65
  • Estimated time: 2.5 days (20 hours)
  • Complexity: Medium
  • Risk level: Medium-Low (with mitigations)

Specification Status: ✅ Implementation-Ready All Technical Decisions: ✅ Made Rollback Plan: ✅ Defined Success Criteria: ✅ Defined

Ready to implement! 🚀

Version: 1.0 Created: 2025-12-22 Author: Claude (Specification Agent) For: ROA2WEB Unified App Feature