Track 2: Offline-First Architecture Design

ServiceWorker Install → Pre-cache: /rtsport/*, /static/css/*, /static/js/*, /static/data/*
User Request          → Check Cache → Hit → Return cached
                      →   Miss     → Fetch from network → Cache response → Return
Network Available     → Background update of cached assets (Stale-While-Revalidate pattern after install)

User Request API → Network available → Fetch → Cache response → Return
                  → Network fails    → Return cached (if available) → Return error (if no cache)

┌─────────────────────┐     Network Available     ┌─────────────────────┐
│   User creates      │ ────────────────────────→ │   Process Queue     │
│   event offline     │                            │                     │
│                     │                            │  POST /events/...   │
│  Event saved to     │      ┌──────────────┐      │  Response 201 →     │
│  IndexedDB (pending) │      │ Periodic     │      │  Update local ID    │
│  sync_queue entry   │      │ Sync Timer   │      │  Mark as synced     │
│  created            │      │ (every 30s   │      │  Remove from queue  │
└─────────────────────┘      │ when online) │      └─────────────────────┘
                              └──────────────┘
                                      │
                              Network Not Available
                                      │
                                      ▼
                              ┌─────────────────────┐
                              │ Queue persists.      │
                              │ Retry on next        │
                              │ network event.       │
                              └─────────────────────┘

processSyncQueue():
  while queue not empty:
    item = dequeue()
    try:
      response = fetch(item.endpoint, { method: item.method, body: item.body, headers: auth headers })
      if response.ok:
        data = await response.json()
        updateLocalEvent(item.localId, { serverId: data.id, syncStatus: 'synced' })
        markQueueItemComplete(item.id)
      else if response.status == 401:
        // Token expired — need re-auth
        pauseQueue()
        notifyUser('Session expired. Please log in to sync')
        break
      else:
        // 4xx/5xx — retry logic
        item.retryCount++
        if item.retryCount >= 3:
          markQueueItemFailed(item.id, response.statusText)
        else:
          reEnqueue(item, backoffDelay(item.retryCount))
    except NetworkError:
      // No connectivity — break out, try again later
      break

pullLatestData():
  athletes = fetch('/api/v1/roster?school_id=...')
  mergeIntoLocal('athletes', athletes)

  cases = fetch('/api/v1/cases/athlete/*' for watched athletes)
  mergeIntoLocal('cases', cases)

  // Don't delete pending local events — they have higher precedence

Login Online:
  POST /api/v1/auth/login/json → JWT + role + school_id + exp
  Store in auth_cache (IndexedDB)
  Start offline grace period timer

Offline:
  checkAuth() reads from auth_cache
  Token valid (not expired) → proceed with cached token
  Token expired → show "Session expired" → redirect to login
  No cached token → redirect to login (login page itself is cached)

Grace Period:
  Allow offline use for up to N hours past token expiry
  Configured per-role (shorter for admin, longer for AT)
  Default: 4 hours for AT, 2 hours for coach, 1 hour for parent

Store in IndexedDB auth_cache (not encrypted — same trust model as localStorage)
Remove on logout
Remove on token expiry + grace period expiry

App loads → checkAuth():
  if online:
    fetch('/api/v1/auth/me') with cached token
    if 200:
      token valid → refresh grace_period timer
      return token
    elif 401:
      try auto-login from stored creds? No — too dangerous
      redirect to login page
  else (offline):
    token = getCachedToken()
    if token:
      if token.exp > now:
        return token
      elif token.exp + grace_period > now:
        return token (degraded mode — warn user)
      else:
        show "Session expired" → redirect to login
    else:
      redirect to login

User opens sideline entry → Already offline → ServiceWorker serves cached HTML+CSS+JS
                                              → checkAuth() returns cached token (within grace period)
                                              → Proceed to sideline entry screen

Tap 1: Select athlete
  Search from IndexedDB athletes store (synced during last online session)
  ✅ Full offline search — no network needed

Tap 2: Select body part
  Body parts loaded from IndexedDB (or static JSON, cached aggressively)
  ✅ Full offline — body parts rarely change

Tap 3: Select severity + removed_from_play → Submit
  Create event object:
    {
      id: "local_evt_uuid",  // Client-generated UUID
      event_type: "sideline_entry",
      content: {
        athlete_id: "ath_001",
        body_part: "Ankle - Right",
        severity: "moderate",
        removed_from_play: true,
        note: "Rolled ankle during third quarter"
      },
      timestamp: "2026-05-09T14:30:00Z",  // When injury happened, not when synced
      syncStatus: "pending"
    }

  Save to IndexedDB events store → show confirmation toast
  Create sync_queue entry → POST /api/v1/events/sideline-entry with same payload

  ✅ Complete — event exists locally, sync happens when connectivity returns

On connectivity restored:
  Process sync queue → POST to server → Server 201 Created
  Update local event: syncStatus = "synced", localId → serverId
  Pull updated data (case opened, athlete status changed)

const CACHE_VERSION = 'v1';
const STATIC_CACHE = `rtsport-static-${CACHE_VERSION}`;
const API_CACHE = `rtsport-api-${CACHE_VERSION}`;

const STATIC_ASSETS = [
  '/rtsport/',
  '/rtsport/coach',
  '/rtsport/parent',
  '/rtsport/at',
  '/rtsport/ad',
  '/rtsport/login',
  '/rtsport/static/css/rtsport.css',
  '/rtsport/static/css/dashboard-tabs.css',
  '/rtsport/static/css/parent-tabs.css',
  '/rtsport/static/css/login.css',
  '/rtsport/static/css/admin-tabs.css',
  '/rtsport/static/js/dashboard-tabs.js',
  '/rtsport/static/js/parent-tabs.js',
  '/rtsport/static/js/login.js',
  '/rtsport/static/js/admin-tabs.js',
  '/rtsport/static/js/mock-data.js',
  '/rtsport/static/data/body-parts.json',
];

// Install: pre-cache all static assets
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(STATIC_CACHE).then(cache => cache.addAll(STATIC_ASSETS))
  );
  self.skipWaiting();
});

// Activate: clean old caches
self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(keys => 
      Promise.all(keys.filter(k => k !== STATIC_CACHE && k !== API_CACHE).map(k => caches.delete(k)))
    )
  );
  self.clients.claim();
});

// Fetch: static → Cache First, API → Network First
self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);

  // Static assets: Cache First
  if (url.pathname.startsWith('/rtsport/static/') || 
      url.pathname === '/rtsport/' ||
      url.pathname.match(/^\/rtsport\/(coach|parent|at|ad|login)$/)) {
    event.respondWith(cacheFirst(event.request));
    return;
  }

  // API dashboard/roster endpoints: Network First
  if (url.pathname.startsWith('/api/v1/dashboard/') ||
      url.pathname.startsWith('/api/v1/roster') ||
      url.pathname.startsWith('/api/v1/body-parts')) {
    event.respondWith(networkFirst(event.request));
    return;
  }

  // Everything else: Network Only (including mutations)
  return;
});

async function cacheFirst(request) {
  const cached = await caches.match(request);
  return cached || fetch(request);
}

async function networkFirst(request) {
  try {
    const response = await fetch(request);
    const cache = await caches.open(API_CACHE);
    cache.put(request, response.clone());
    return response;
  } catch (e) {
    const cached = await caches.match(request);
    return cached || new Response(null, { status: 503 });
  }
}

<!-- In each dashboard.html, add: -->
<script>
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/rtsport/sw.js')
    .then(() => console.log('RTSport SW registered'))
    .catch(e => console.error('RTSport SW failed:', e));
}
</script>

                    ┌─────────────────────────────┐
                    │    User enters sideline      │
                    │    (No Internet)             │
                    └─────────────┬───────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │ ServiceWorker intercepts     │
                    │ HTML/CSS/JS → Cache Hit     │
                    │ Serves from rtsport-static-v1│
                    └─────────────┬───────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │ checkAuth():                 │
                    │ IndexedDB auth_cache →       │
                    │ token exists, not expired    │
                    │ Returns cached JWT           │
                    └─────────────┬───────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │ loadSidelineEntry():         │
                    │ IndexedDB athletes store →   │
                    │ Athlete list for search      │
                    │ IndexedDB bodyParts store →  │
                    │ Body part categories         │
                    └─────────────┬───────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │ User completes 3-tap entry   │
                    │ Tap → Tap → Tap → Submit    │
                    └─────────────┬───────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │ 1. Generate local UUID       │
                    │ 2. Save to IndexedDB events  │
                    │    syncStatus: "pending"     │
                    │ 3. Add to sync_queue         │
                    │ 4. Show confirmation toast   │
                    │ 5. Reset entry form          │
                    │ 6. Return to dashboard       │
                    └─────────────┬───────────────┘
                                  │
                        Network Returns (30s later)
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │ window.online fires →        │
                    │ processSyncQueue():           │
                    │ POST /api/v1/events/          │
                    │ sideline-entry               │
                    │ Server: 201 Created          │
                    │ Update local: syncStatus=     │
                    │ "synced", serverId assigned  │
                    │ Remove from sync_queue       │
                    │ Pull fresh roster/cases      │
                    │ Show "Synced!" toast         │
                    └─────────────────────────────┘