# 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`.