317 lines
9.5 KiB
Markdown
317 lines
9.5 KiB
Markdown
# Job-Info-Test → Job-Info-Prod Migration Plan
|
|
|
|
## Current State: Job-Info-Test ✅
|
|
|
|
**Status:** Documentation Complete, Architecture Confirmed
|
|
|
|
### What Exists
|
|
- ✅ Functional PocketBase + Microsoft OAuth integration (half-working)
|
|
- ✅ Hono backend with Redis caching
|
|
- ✅ Frontend with auth.js and index.html
|
|
- ✅ Tailwind CSS + PostCSS setup
|
|
- ✅ Comprehensive professional documentation (8 docs)
|
|
- ✅ Architecture specification with dual-token system
|
|
|
|
### What's Documented
|
|
```
|
|
📚 Professional Documentation Suite
|
|
├── auth/README.md (Project overview)
|
|
├── auth/INDEX.md (Navigation guide)
|
|
├── auth/ONBOARDING.md (Getting started)
|
|
├── auth/RULES.md (Data handling + dual-token rules)
|
|
├── auth/FLOWMAP.md (Architecture diagrams)
|
|
├── auth/VIEWS.md (UI specifications)
|
|
├── auth/TECH_STACK.md (Technology enforcement)
|
|
├── auth/DOCUMENTATION_SUMMARY.md (What was created)
|
|
├── OPUS_PROMPT_PHASE1.md (Scaffolding prompt - 671 lines)
|
|
├── PRODUCTION_MIGRATION_PLAN.md (Implementation roadmap)
|
|
└── DOCUMENTATION_COMPLETE.md (Completion summary)
|
|
```
|
|
|
|
### Key Requirements Now Clear
|
|
1. **Dual-token system** (PocketBase + Microsoft Graph)
|
|
2. **Always-warm tokens** via background refresh loop
|
|
3. **Zero re-authentication** after initial login
|
|
4. **Field-deployed app** for construction workers
|
|
5. **Offline-first** with graceful degradation
|
|
|
|
---
|
|
|
|
## Phase 1: Job-Info-Prod Scaffolding (Ready)
|
|
|
|
**Note:** `Job-Info-Prod` is a **temporary staging folder** for safety. Once everything is verified working, it will **replace** Job-Info-Test entirely. The separate folder is just to keep things safe during development.
|
|
|
|
### ✅ Pre-Work Complete
|
|
- ✅ Architecture documented (OPUS_PROMPT_PHASE1.md)
|
|
- ✅ Requirements clarified
|
|
- ✅ Tech stack specified
|
|
- ✅ Rules documented
|
|
- ✅ Patterns established
|
|
|
|
### 🔄 Next: Run Opus 4.5 Scaffolding
|
|
|
|
**Input:**
|
|
- OPUS_PROMPT_PHASE1.md (671 lines of detailed architecture)
|
|
- Supporting docs from auth/ folder
|
|
|
|
**Output:**
|
|
- Complete Job-Info-Prod folder structure
|
|
- All service files (tokenService, cacheService, pocketbaseService, graphService)
|
|
- Route handlers with proper patterns
|
|
- Frontend components scaffolding
|
|
- Configuration templates
|
|
- Tests structure
|
|
- Professional documentation
|
|
|
|
**Duration:** ~30 minutes with Opus 4.5
|
|
|
|
---
|
|
|
|
## Phase 2: Implementation (Sonnet 4.5)
|
|
|
|
### Backend Implementation
|
|
```
|
|
Routes:
|
|
├── /api/auth/login-callback (Initial token setup)
|
|
├── /api/auth/logout (Clear cache + stop refresh)
|
|
└── /api/refresh-token (Get fresh tokens)
|
|
|
|
Services:
|
|
├── TokenRefreshService (30-min background loop)
|
|
├── CacheService (Valkey operations)
|
|
├── PocketBaseService (PocketBase integration)
|
|
└── GraphService (Microsoft Graph integration)
|
|
|
|
Middleware:
|
|
├── Auth verification (Token validation)
|
|
└── Error handling (Consistent responses)
|
|
```
|
|
|
|
### Frontend Implementation
|
|
```
|
|
Auth:
|
|
├── TokenClient (ensureToken pattern)
|
|
├── PocketBase setup (Client initialization)
|
|
└── Refresh loop startup (On app init)
|
|
|
|
Views:
|
|
├── Sign in page (OAuth flow)
|
|
├── Jobs list (Main app)
|
|
├── Job detail + files (File operations)
|
|
└── Notes page (Sticky notes)
|
|
|
|
Services:
|
|
├── API client (Token injection)
|
|
├── Cache service (Local file caching)
|
|
├── Offline handler (Graceful degradation)
|
|
└── State management (Global state)
|
|
```
|
|
|
|
**Duration:** ~4-6 hours with Sonnet 4.5
|
|
|
|
---
|
|
|
|
## Phase 3: Integration & Testing
|
|
|
|
### What Gets Tested
|
|
- ✅ Dual-token obtention in single OAuth flow
|
|
- ✅ Token storage (localStorage + Valkey)
|
|
- ✅ Background refresh loop (every 30 minutes)
|
|
- ✅ API calls with token injection
|
|
- ✅ Offline fallback with stale tokens
|
|
- ✅ Error handling & graceful degradation
|
|
- ✅ Logout clears all tokens
|
|
|
|
### Files to Create
|
|
- Tests for token lifecycle
|
|
- Tests for background refresh
|
|
- Tests for offline mode
|
|
- Documentation for each component
|
|
|
|
---
|
|
|
|
## Phase 4: Production Deployment
|
|
|
|
### Pre-Deployment Checklist
|
|
- [ ] All tests passing
|
|
- [ ] Error logging configured
|
|
- [ ] Performance testing done
|
|
- [ ] Security review complete
|
|
- [ ] Documentation finalized
|
|
- [ ] Deployment guide created
|
|
|
|
### Deployment Steps
|
|
1. Build frontend (Tailwind + TypeScript)
|
|
2. Build backend (Hono + TypeScript)
|
|
3. Deploy to server
|
|
4. Configure Valkey/Redis
|
|
5. Set environment variables
|
|
6. Start background services
|
|
7. Test end-to-end
|
|
|
|
---
|
|
|
|
## File Structure Summary
|
|
|
|
### Current Job-Info-Test
|
|
```
|
|
/home/admin/Job-Info-Test/
|
|
├── frontend/
|
|
│ ├── index.html
|
|
│ ├── signin.html
|
|
│ ├── auth.js (PocketBase auth - basic)
|
|
│ └── assets/
|
|
├── backend/
|
|
│ ├── server.ts (Hono server)
|
|
│ └── redis-cache.ts (Cache operations)
|
|
├── auth/ (📚 Documentation)
|
|
│ ├── RULES.md
|
|
│ ├── FLOWMAP.md
|
|
│ ├── VIEWS.md
|
|
│ ├── TECH_STACK.md
|
|
│ └── ... (8 docs total)
|
|
├── OPUS_PROMPT_PHASE1.md (🎯 Scaffolding prompt)
|
|
└── ... (config files, package.json, etc.)
|
|
```
|
|
|
|
### Future Job-Info-Prod (Will Be Created)
|
|
```
|
|
/home/admin/Job-Info-Prod/ (NEW)
|
|
├── frontend/
|
|
│ ├── public/
|
|
│ │ ├── index.html
|
|
│ │ ├── signin.html
|
|
│ │ └── offline.html
|
|
│ └── src/
|
|
│ ├── main.ts
|
|
│ ├── auth/
|
|
│ │ ├── client.ts (🔑 Token management)
|
|
│ │ └── pocketbase.ts
|
|
│ ├── views/
|
|
│ ├── services/
|
|
│ └── components/
|
|
├── backend/
|
|
│ ├── src/
|
|
│ │ ├── index.ts
|
|
│ │ ├── routes/ (auth, jobs, files, etc.)
|
|
│ │ ├── services/ (token, cache, pb, graph)
|
|
│ │ ├── middleware/
|
|
│ │ └── types/
|
|
│ └── tests/
|
|
├── shared/ (Types shared between frontend & backend)
|
|
├── docs/ (Architecture, API reference, etc.)
|
|
├── package.json
|
|
├── tsconfig.json
|
|
└── ... (config files)
|
|
```
|
|
|
|
---
|
|
|
|
## Critical Success Metrics
|
|
|
|
### For Phase 1 (Scaffolding)
|
|
- ✅ All files generated
|
|
- ✅ Structure matches specification
|
|
- ✅ All imports resolve
|
|
- ✅ No compilation errors
|
|
|
|
### For Phase 2 (Implementation)
|
|
- ✅ Login flow works end-to-end
|
|
- ✅ Both tokens obtained
|
|
- ✅ Background refresh runs
|
|
- ✅ API calls inject tokens
|
|
- ✅ Offline mode works
|
|
|
|
### For Phase 3 (Testing)
|
|
- ✅ 100% token lifecycle coverage
|
|
- ✅ Background refresh tested
|
|
- ✅ Offline scenarios tested
|
|
- ✅ Error cases handled
|
|
|
|
### For Phase 4 (Production)
|
|
- ✅ Zero re-authentication after login
|
|
- ✅ Field workers can use offline
|
|
- ✅ Graceful degradation when down
|
|
- ✅ Mission-critical reliability
|
|
|
|
---
|
|
|
|
## Timeline Estimate
|
|
|
|
| Phase | Work | Duration | Tool |
|
|
|-------|------|----------|------|
|
|
| 1 | **Scaffolding** | 30 min | Opus 4.5 |
|
|
| 2 | **Implementation** | 4-6 hrs | Sonnet 4.5 |
|
|
| 3 | **Testing** | 2-3 hrs | Manual + Bun test |
|
|
| 4 | **Deployment** | 1-2 hrs | Manual |
|
|
| **Total** | | **8-12 hours** | |
|
|
|
|
---
|
|
|
|
## Key Documents
|
|
|
|
### For Scaffolding (Opus 4.5)
|
|
📄 **[OPUS_PROMPT_PHASE1.md](OPUS_PROMPT_PHASE1.md)** (671 lines)
|
|
- Complete architecture specification
|
|
- Dual-token system details
|
|
- Project structure
|
|
- Code examples
|
|
- Tech stack enforcement
|
|
|
|
### For Implementation (Sonnet 4.5)
|
|
📄 **[auth/RULES.md](auth/RULES.md)** - Implementation rules
|
|
📄 **[auth/TECH_STACK.md](auth/TECH_STACK.md)** - Technology enforcement
|
|
📄 **[auth/VIEWS.md](auth/VIEWS.md)** - UI specifications
|
|
|
|
### For Reference (Developers)
|
|
📄 **[auth/ONBOARDING.md](auth/ONBOARDING.md)** - Getting started
|
|
📄 **[auth/FLOWMAP.md](auth/FLOWMAP.md)** - Architecture diagrams
|
|
📄 **[auth/INDEX.md](auth/INDEX.md)** - Navigation guide
|
|
|
|
---
|
|
|
|
## What's Different from Job-Info-Test
|
|
|
|
### Architecture Improvements
|
|
| Aspect | Job-Info-Test | Job-Info-Prod |
|
|
|--------|---------------|---------------|
|
|
| Tokens | Attempted single | ✅ Dual (PB + Graph) |
|
|
| Refresh | Manual / Broken | ✅ Automatic loop |
|
|
| Re-auth | Required after expiry | ✅ Never (field workers!) |
|
|
| Offline | Not designed for | ✅ Graceful fallback |
|
|
| Cache | Basic Redis | ✅ Valkey + strategy |
|
|
| Structure | Ad-hoc | ✅ Professional layout |
|
|
| Docs | Scattered | ✅ Comprehensive |
|
|
| Testing | Minimal | ✅ Structured tests |
|
|
|
|
---
|
|
|
|
## Ready to Go?
|
|
|
|
### What You Have
|
|
✅ **Complete architecture specification** (OPUS_PROMPT_PHASE1.md)
|
|
✅ **All requirements documented** (RULES.md)
|
|
✅ **Tech stack enforced** (TECH_STACK.md)
|
|
✅ **Professional structure planned** (In prompt)
|
|
✅ **Code examples provided** (In prompt + RULES.md)
|
|
|
|
### What's Next
|
|
1. Share OPUS_PROMPT_PHASE1.md with Opus 4.5
|
|
2. Opus scaffolds Job-Info-Prod structure
|
|
3. Share scaffolding output with Sonnet 4.5
|
|
4. Sonnet implements functionality
|
|
5. Merge and test
|
|
6. Deploy to production
|
|
|
|
---
|
|
|
|
## Note on Architecture
|
|
|
|
This dual-token, always-warm-cache approach is specifically designed for:
|
|
- **Field workers** who can't afford re-authentication delays
|
|
- **Intermittent connectivity** in field environments
|
|
- **Mission-critical reliability** - app must always work
|
|
- **Enterprise integration** - PocketBase + Microsoft ecosystem
|
|
|
|
It's not overkill, it's the right tool for the job. ✨
|