506 lines
26 KiB
Markdown
506 lines
26 KiB
Markdown
# 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:
|
|
|
|
1. **Initialization** → Check auth → Show Auth or Landing
|
|
2. **Landing Page** → Jobs list with search/filter → Cache-backed
|
|
3. **Job Detail** → File list (cached) → File categories → Preview
|
|
4. **Notes** → Expanded sticky notes view
|
|
5. **Sign Out** → Clear all state → Return to Auth
|
|
|
|
All caching, filtering, and state management follows the rules in `RULES.md`.
|