26 KiB
26 KiB
Application Flow Map
Version: 1.0
Last Updated: January 2026
High-Level Application Flow
┌─────────────────────────────────────────────────────────────────────┐
│ USER JOURNEY - JOB INFO APP │
└─────────────────────────────────────────────────────────────────────┘
┌──────────┐
│ App Load │
└────┬─────┘
│
▼
┌──────────────────────────┐
│ Check Auth Session │
│ (Check localStorage) │
└────┬─────┬──────────────┘
│ │
Valid Invalid
│ │
│ ▼
│ ┌──────────────────┐
│ │ AuthView │
│ │ (Sign In Page) │
│ └────┬─────────────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │ User Logs In │
│ │ Token Stored │
│ └────┬─────────────┘
│ │
└───────┴──────────────────┐
│
▼
┌────────────────────┐
│ LandingView (Home) │
│ - Header │
│ - Job Cards Grid │
│ - Search Bar │
│ - Filters │
└────┬────────────────┘
│
┌────────┴────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ SEARCH │ │ FILTER │
│ (by term) │ │ (by status, │
│ │ │ date) │
└──────┬───────┘ └──────┬───────┘
│ │
└────────┬────────┘
│
▼
┌──────────────────────┐
│ APPLY CACHE │
│ (jobs:page:1:...) │
│ │
│ Hit: Return cached │
│ Miss: Fetch from PB │
│ → Cache it │
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ Display Job Cards │
│ (Sorted by Job #) │
└──────┬───────────────┘
│
┌───────────────┴────────────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌────────────────────┐
│ Click Card │ │ Sign Out Button │
│ → Fetch Job Files │ │ → Clear Auth │
│ → Open Job Detail │ │ → Clear Cache │
└─────┬───────────────┘ │ → Return to Auth │
│ └────────────────────┘
▼
┌─────────────────────────────┐
│ ManagerInfoView │
│ (Job Detail Page) │
│ │
│ ┌─────────────────────────┐ │
│ │ Job Header │ │
│ │ - Job #, Name, Status │ │
│ │ - Manager, Contact Info │ │
│ │ - Dates, etc │ │
│ └─────────────────────────┘ │
│ │
│ ┌─────────────────────────┐ │
│ │ File List Section │ │
│ │ - Search Files Input │ │
│ │ - Categorized Files │ │
│ │ * Manager Info │ │
│ │ * Contracts │ │
│ │ * Submittals │ │
│ │ * Plans │ │
│ │ * Other │ │
│ │ - Preview/Open Buttons │ │
│ └─────────────────────────┘ │
│ │
│ ┌─────────────────────────┐ │
│ │ Notes Section (Read) │ │
│ │ - Sticky Notes Display │ │
│ │ - Click → Expand View │ │
│ └─────────────────────────┘ │
└─────┬───────────────────────┘
│
┌───┴────────────────────┐
│ │
▼ ▼
┌─────────────┐ ┌──────────────────┐
│ File Cache │ │ NotesView │
│ Check │ │ (Expanded Notes) │
│ │ │ │
│ Hit: Use │ │ - Full Notes │
│ Miss: Fetch │ │ - Back Button │
│ Cache │ │ │
└─────┬───────┘ └──────┬───────────┘
│ │
▼ │
┌─────────────┐ │
│ Display │ │
│ Files by │ │
│ Category │ │
└─────┬───────┘ │
│ │
▼ │
┌─────────────────────────┐ │
│ User Actions: │ │
│ - Search within files │ │
│ - Click Preview │ │
│ - Click Download │ │
│ - Click Notes → Expand │ │
│ - Back to Job Detail │ │
└─────┬───────────────────┘ │
│ │
└─────────┬───────────┘
│
▼
┌──────────────────┐
│ Back to Landing │
│ or Sign Out │
└──────────────────┘
Data Flow Diagram
┌─────────────────────────────────────────────────────────────────┐
│ DATA FLOW │
└─────────────────────────────────────────────────────────────────┘
FRONTEND BACKEND EXTERNAL
┌────────────┐ ┌──────────────┐
│ Browser │ │ Hono Server │
│ index.html │ │ (port 3005) │
│ │ │ │
│ ▼ GET / │ │ ▼ Serve │
│ index.html │ │ Static Files │
└────────────┘ │ │
│ │ ▼ GET /api/ │
│ │ jobs │
│ │ │
▼ │ ▼ Check │ ┌──────────┐
┌──────────────┐ │ Cache │ │ Redis/ │
│ auth.js │ │ │ │ Valkey │
│ (PocketBase) │◄────────────┤ Cache Hit? │◄────►│ Cache │
│ │ │ │ │ │
│ ▼ Login │ │ No → Fetch │ └──────────┘
│ Store Token │ │ from PB │
│ │ │ │ ┌──────────┐
└──────┬───────┘ │ ▼ Transform │ │Pocket │
│ │ Data │ │Base │
▼ │ │ │API │
┌──────────────┐ │ ▼ Cache it │ │ │
│ index.html │ │ │ └──────────┘
│ Loaded │ │ ▼ Return │
│ │ │ JSON │
│ ▼ Fetch │─────────────►│ │
│ /api/jobs │ │ ▼ GET /api/ │
│ (w/ headers) │ │ job-files │
│ │ │ │
│ ▼ Display │◄─────────────┤ Fetch files │
│ Job Cards │ │ Return JSON │
│ │ │ │
│ ▼ Search/ │ │ ▼ Stream │ ┌──────────┐
│ Filter │─────────────►│ /api/job- │ │ Share │
│ │ │ file-content│─────►│Point/ │
│ ▼ Click Job │ │ │ │Graph │
│ │ │ ▼ Serve │ │API │
│ ▼ Fetch Job │─────────────►│ Files │ │ │
│ Files │ │ (streaming) │ └──────────┘
│ (fileCache) │ │ │
│ │◄─────────────┘ │
│ ▼ Display │ │
│ File List │ │
│ │ │
│ ▼ User │ │
│ Actions │ │
│ (preview, │ │
│ download, │ │
│ notes) │ │
└──────────────┘ │
┌──────────┘
Caching Flow
┌──────────────────────────────────────────────────┐
│ CACHE FLOW │
└──────────────────────────────────────────────────┘
Request: /api/jobs?page=1&perPage=10&sort=-Job_Number
│
▼
┌────────────────────┐
│ Generate Cache Key │
│ "jobs:page:1:... │
└────────┬───────────┘
│
▼
┌─────────────────────────┐
│ Check Redis │
│ getCache(cacheKey) │
└────┬────────────────────┘
│
Hit?
┌─┴─┐
│ │
Yes No
│ │
│ ▼
│ ┌────────────────────────┐
│ │ Fetch from PocketBase │
│ │ API │
│ └────────┬───────────────┘
│ │
│ ▼
│ ┌────────────────────────┐
│ │ Transform Data │
│ │ (filter, sort, format) │
│ └────────┬───────────────┘
│ │
│ ▼
│ ┌────────────────────────┐
│ │ setCache(key, data, │
│ │ ttl=300) │
│ └────────┬───────────────┘
│ │
└──────┬───┘
│
▼
┌─────────────┐
│ Return JSON │
│ to Client │
└─────────────┘
State Management Flow
┌──────────────────────────────────────────────────┐
│ FRONTEND STATE MANAGEMENT │
└──────────────────────────────────────────────────┘
Global State Object: "fileListState"
fileListState = {
items: [], ◄── File list data
filter: '', ◄── Search term
jobNumber: '', ◄── Current job #
jobName: '' ◄── Current job name
}
Modifications Flow:
┌───────────────────────┐
│ User Interaction │
│ (search, filter, │
│ click job) │
└──────────┬────────────┘
│
▼
┌──────────────────────┐
│ Call Update Function │
│ (renderFileGroups, │
│ onJobClick, etc) │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Modify State Object │
│ │
│ fileListState.filter │
│ = "new value" │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Re-render View │
│ (DOM updates) │
└──────────────────────┘
Authentication Flow
┌──────────────────────────────────────────────────┐
│ AUTHENTICATION FLOW │
└──────────────────────────────────────────────────┘
1. APP LOAD
│
▼
Check localStorage for "pocketbase_auth"
│
┌──────────────────┐
│ Valid Session? │
└──┬──────────────┬┘
YES NO
│ │
│ ▼
│ ┌─────────────┐
│ │ AuthView │
│ │ (signin.html)
│ │ │
│ │ User enters:│
│ │ • Email │
│ │ • Password │
│ └─────┬───────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │ PocketBase Login │
│ │ pb.collection() │
│ │ .authWithPassword()
│ └─────┬────────────┘
│ │
│ ▼
│ ┌──────────────────────┐
│ │ Token Received │
│ │ (single token!) │
│ │ │
│ │ localStorage.set( │
│ │ 'pocketbase_auth', │
│ │ { token: ... }) │
│ └─────┬────────────────┘
│ │
└───────┬───────┘
│
▼
┌───────────────────┐
│ LandingView Load │
│ (with auth token) │
└─────────┬─────────┘
│
▼
┌───────────────────────────┐
│ All API Requests Use: │
│ │
│ fetch('/api/jobs', { │
│ headers: { │
│ 'Authorization': │
│ 'Bearer ' + token │
│ } │
│ }) │
└───────────────────────────┘
2. SIGN OUT
│
▼
User clicks "Sign Out"
│
▼
┌─────────────────────────────┐
│ Clear Auth │
│ • localStorage.removeItem │
│ ('pocketbase_auth') │
│ • sessionStorage.clear() │
│ • pb.authStore.clear() │
│ • fileCache.clear() │
└────────┬────────────────────┘
│
▼
┌────────────────────┐
│ Reload Page │
│ location.reload() │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ AuthView (signin) │
└────────────────────┘
View Hierarchy
┌─────────────────────────────────────────────────────────┐
│ App Root │
└──────────────┬──────────────────────────────────────────┘
│
┌────────┴─────────┐
│ │
▼ ▼
┌─────────┐ ┌──────────────────┐
│ AuthView│ │ LandingView │
│ │ │ (Home) │
│ - Login │ │ │
│ - Signin│ │ ┌──────────────┐ │
│ Form │ │ │ Header │ │
│ │ │ │ - User Info │ │
└─────────┘ │ │ - Sign Out │ │
│ └──────────────┘ │
│ │
│ ┌──────────────┐ │
│ │ JobCardView │ │
│ │ │ │
│ │ - Search Bar │ │
│ │ - Filters │ │
│ │ - Job Cards │ │
│ │ (Grid) │ │
│ │ │ │
│ │ Card Click ──┼─┼──┐
│ │ triggers │ │ │
│ └──────────────┘ │ │
└──────────────────┘ │
│
▼
┌─────────────────────┐
│ ManagerInfoView │
│ (Job Detail) │
│ │
│ ┌─────────────────┐ │
│ │ Job Header │ │
│ │ - Job #, Name │ │
│ │ - Manager, Info │ │
│ └─────────────────┘ │
│ │
│ ┌─────────────────┐ │
│ │ FileListView │ │
│ │ │ │
│ │ - File Search │ │
│ │ - File Groups │ │
│ │ │ │
│ │ Preview Click ──┼─┼──┐
│ │ triggers │ │ │
│ └─────────────────┘ │ │
│ │ │
│ ┌─────────────────┐ │ │
│ │ NotesSection │ │ │
│ │ │ │ │
│ │ - Sticky Notes │ │ │
│ │ - Expand Button │ │ │
│ │ Expand Click │ │ │
│ │ triggers ──┼─┼──┼──┐
│ └─────────────────┘ │ │ │
│ │ │ │
│ Back Button ────────┼──┘ │
└─────────────────────┘ │
│
▼
┌──────────────────────────┐
│ NotesView │
│ (Expanded Notes) │
│ │
│ - Full Notes Content │
│ - Back to JobDetail │
└──────────────────────────┘
Summary
The application follows a clear, intuitive flow:
- Initialization → Check auth → Show Auth or Landing
- Landing Page → Jobs list with search/filter → Cache-backed
- Job Detail → File list (cached) → File categories → Preview
- Notes → Expanded sticky notes view
- Sign Out → Clear all state → Return to Auth
All caching, filtering, and state management follows the rules in RULES.md.