Job-Info/instructions/auth/README.md

Job Info - Enforcement Rules & Guidance

Production-Ready Documentation Suite

This folder contains complete enforcement rules, patterns, and guidance for the Job Info application. All developers must follow these rules for consistency, quality, and professionalism.

---

📚 Documentation Index

Quick Navigation

• Start here: INDEX.md - Task-based navigation
• Getting started: ONBOARDING.md - 5-minute quick start
• Core rules: RULES.md - MOST IMPORTANT - Read first
• Visual diagrams: FLOWMAP.md - Application flows
• UI patterns: VIEWS.md - View architecture
• Tech stack: TECH_STACK.md - Technology versions

Summary

• Overview: DOCUMENTATION_SUMMARY.md - What was created

Implementation

• Auth code: auth-universal.js - Single PocketBase auth

---

🚀 Quick Start

For New Developers

1. Read INDEX.md (2 min)
2. Follow ONBOARDING.md (15 min)
3. Study RULES.md (30 min)

For Specific Tasks

• Check INDEX.md - Find your task → Get directed to right doc
• All docs are cross-referenced and searchable

---

📋 Key Rules

Authentication

• ✅ ONE PocketBase token per user (no Graph tokens)
• ✅ Token obtained at login, reused everywhere
• ✅ Token cached in localStorage
• ✅ Clear all auth on sign out

Caching

• ✅ Cache ALL GET requests in Redis/Valkey
• ✅ Cache key format: noun:filter:value
• ✅ TTL: 5-15 minutes (depends on data freshness)
• ✅ Cache invalidation on mutations

Frontend Styling

• ✅ Use Tailwind CSS utility classes
• ✅ No inline styles
• ✅ No other CSS frameworks

Code Quality

• ✅ Type all functions (TypeScript strict mode)
• ✅ Handle all errors
• ✅ Log important events
• ✅ Follow naming conventions
• ❌ NO any type (except rare justified cases)

File Handling

• ✅ Support: PDF, Word (.doc/.docx), Images (.jpg/.png/.gif/etc)
• ✅ Categories: Manager Info, Contracts, Submittals, Plans, Other
• ✅ Filter by type and search term

---

📁 File Structure

auth/
├── README.md                    (This file - overview)
├── INDEX.md                     (Navigation guide - START HERE)
├── ONBOARDING.md               (Getting started)
├── RULES.md                    (Data handling rules - MOST IMPORTANT)
├── FLOWMAP.md                  (Application flows & diagrams)
├── VIEWS.md                    (UI/View architecture)
├── TECH_STACK.md               (Technology versions & usage)
├── DOCUMENTATION_SUMMARY.md    (What was created)
└── auth-universal.js           (Authentication implementation)

---

✅ Before Committing Code

Use the checklist in INDEX.md:

• All functions have TypeScript types
• No any type annotations
• All errors are caught and logged
• Cache implemented (if GET endpoint)
• Follows naming conventions
• Tests pass
• Code reviewed against RULES.md

---

🔍 Getting Help

1. Check documentation - 80% of questions answered here
2. Search relevant doc - Use browser find (Ctrl+F)
3. Look for examples - TECH_STACK.md and VIEWS.md have code samples
4. Check logs - logs/server.log and logs/error.log
5. Ask team - With problem details, code, and expected behavior

---

📖 How These Docs Are Organized

Document	Purpose	When to Use
INDEX.md	Navigation	Finding what you need
ONBOARDING.md	Getting started	First day, common tasks
RULES.md	Enforcement	Before writing code
FLOWMAP.md	Understanding	How app works
VIEWS.md	UI Development	Building frontend
TECH_STACK.md	Development	Setting up environment

---

🎯 What This Folder Provides

• ✅ Clear Rules - No ambiguity about what's required
• ✅ Best Practices - Industry-standard patterns
• ✅ Code Examples - Real examples you can reference
• ✅ Professional Foundation - Enterprise-level documentation
• ✅ Easy Onboarding - New developers productive in 1-2 hours
• ✅ Consistency - All code follows same patterns
• ✅ Maintainability - Well-documented decisions

---

📞 Documentation Status

• Version: 1.0
• Status: Production Ready
• Created: January 2026
• Quality: Professional / Enterprise
• Coverage: Complete - All rules and patterns documented

---

Ready to get started? → Go to INDEX.md

Secrets and Environment

• For frontend, all secrets are handled by PocketBase OAuth (no client secrets exposed).
• For backend/agent flows, use environment variables and server-side code to store secrets securely.
• The module does not expose or require secrets in the frontend.

Example Test Page

See auth-test.html for a safe way to test all flows without affecting your main app.

Rules for Copilot Instructions

• Always use Auth.use() to set the pattern before requesting tokens. Supported types: 'pb-user', 'pb-agent', 'graph-user', 'graph-agent', or any combination.
• Always use Auth.ensureToken(type) to get a valid token; it will handle refresh and prompt if needed.
• Never store secrets in frontend code; use PocketBase OAuth for user login.
• All login prompts must use the provided popup, never custom dialogs.
• Token keys are immutable: 'pbUserToken', 'pbAgentToken', 'graphUserToken', 'graphAgentToken'.
• User info extraction must use Auth.getUserInfo().
• For agent/app-only tokens, use backend code, environment variables, and optionally Valkey/Redis for secure storage and retrieval.

FAQ

• Can I use this in any project? Yes, as long as you include PocketBase and this module.
• Does it work for both user and agent tokens? Yes, with the correct pattern and backend support for agent tokens (including Valkey/Redis for automation).
• Is the popup customizable? The style can be changed, but the flow must remain consistent for all projects.
• How are secrets handled? Only via backend environment variables for agent tokens; never exposed in frontend.

---

For further integration, see the comments in auth-universal.js and the example test page.