9.5 KiB
9.5 KiB
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
- Dual-token system (PocketBase + Microsoft Graph)
- Always-warm tokens via background refresh loop
- Zero re-authentication after initial login
- Field-deployed app for construction workers
- 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
- Build frontend (Tailwind + TypeScript)
- Build backend (Hono + TypeScript)
- Deploy to server
- Configure Valkey/Redis
- Set environment variables
- Start background services
- 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 (671 lines)
- Complete architecture specification
- Dual-token system details
- Project structure
- Code examples
- Tech stack enforcement
For Implementation (Sonnet 4.5)
📄 auth/RULES.md - Implementation rules 📄 auth/TECH_STACK.md - Technology enforcement 📄 auth/VIEWS.md - UI specifications
For Reference (Developers)
📄 auth/ONBOARDING.md - Getting started 📄 auth/FLOWMAP.md - Architecture diagrams 📄 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
- Share OPUS_PROMPT_PHASE1.md with Opus 4.5
- Opus scaffolds Job-Info-Prod structure
- Share scaffolding output with Sonnet 4.5
- Sonnet implements functionality
- Merge and test
- 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. ✨