# 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**:
```bash
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