Job-Info/instructions/auth/INDEX.md

Auth Folder Documentation Index

All enforcement rules, patterns, and guidance for Job Info

---

📚 Documentation Files

For First-Time Setup & Questions

• ONBOARDING.md ← START HERE
  • Quick start (5 minutes)
  • Project structure overview
  • Common tasks
  • Debugging tips
  • FAQ

Core Rules & Patterns

• RULES.md ← READ THIS FIRST
  • Authentication rules (single token)
  • Caching strategy (Redis/Valkey)
  • Data filtering & transformation
  • State management
  • API response formats
  • Naming conventions
  • Testing rules
  • Error handling
  • Logging rules

Application Design

• FLOWMAP.md

  • High-level user journey
  • Data flow diagram
  • Cache flow
  • State management flow
  • Authentication flow
  • View hierarchy

• VIEWS.md

  • View architecture
  • AuthView (Sign In)
  • LandingView (Jobs List)
  • ManagerInfoView (Job Detail)
  • NotesView (Expanded Notes)
  • FilePreviewModal
  • Component standards (buttons, cards, badges)
  • Responsive design
  • Accessibility standards

Technology Stack

• TECH_STACK.md
  • Bun (runtime) - latest
  • Hono (web framework) - ^4.10.8
  • PostCSS - ^8.5.6
  • Tailwind CSS - ^4.1.18
  • TypeScript - ^5
  • ioredis (cache client) - ^5.x
  • PocketBase SDK - ^0.26.5
  • dotenv - ^17.2.3
  • Installation, configuration, and usage patterns

Auth Implementation

• auth-universal.js
  • Single PocketBase authentication
  • Token storage & retrieval
  • Sign out logic

---

🚀 Quick Navigation by Task

"I'm new, where do I start?"

1. Read ONBOARDING.md
2. Set up dev environment (5 min)
3. Read RULES.md (30 min)

"I need to add a new API endpoint"

1. Check RULES.md - Cache Strategy
2. Check TECH_STACK.md - Hono Patterns
3. Follow ONBOARDING.md - Adding New Endpoint

"I need to create a new view/page"

1. Check VIEWS.md - View Architecture
2. Check FLOWMAP.md - User Flow
3. Follow ONBOARDING.md - Adding New View

"I need to understand how data flows"

1. Read FLOWMAP.md - Data Flow Diagram
2. Check RULES.md - Caching Strategy
3. Review TECH_STACK.md - ioredis Usage

"I'm stuck or debugging an error"

1. Check ONBOARDING.md - Debugging section
2. Review RULES.md - Error Handling
3. Search logs in logs/ folder

"I need to modify auth behavior"

1. Review auth-universal.js
2. Check RULES.md - Authentication & Token Rules
3. Test in ONBOARDING.md - Testing section

---

📋 Rules Checklist

Before committing, ensure:

Code Quality

• All functions have TypeScript types
• No any type annotations (except justifiable cases)
• All errors are caught and logged
• Follows RULES.md naming conventions

Authentication

• Uses single PocketBase token (no Graph tokens)
• Token obtained at login, reused everywhere
• No repeated reauthentication
• Sign out clears all state

Caching (Backend)

• GET requests cached
• Cache key follows noun:filter:value format
• TTL appropriate (5-30 minutes)
• Cache invalidation on mutations
• Cache hit/miss logged

Frontend

• Uses Tailwind for all styling (no inline styles)
• No hardcoded secrets
• State changes go through designated functions
• File filtering correct (PDF, Word, Image only)
• Files categorized correctly

Testing

• Tests mock external APIs
• Core logic tested
• No test dependencies on Redis/PocketBase

Documentation

• New endpoints documented in API.md
• New data patterns documented in RULES.md
• New views documented in VIEWS.md
• Code comments explain "why", not "what"

---

🔄 When to Update Documentation

Change	Update
New API endpoint	API.md
New data pattern	RULES.md
New view/page	VIEWS.md
Modify cache strategy	RULES.md
Modify auth flow	RULES.md, FLOWMAP.md
Modify tech stack	TECH_STACK.md
Update development process	ONBOARDING.md

---

📞 Getting Help

1. Check documentation - 80% of questions answered here
2. Search codebase - Find similar patterns
3. Check logs - logs/server.log and logs/error.log
4. Ask team - Include: problem, code, expected behavior

---

Key Principles

Principle	Why	What to Do
Single Source of Truth	Avoid confusion	One auth module, one state object
Explicit Over Implicit	Readability	Type all functions, name clearly
Fail Fast	Debugging	Validate input, log errors immediately
Reuse Over Reinvent	Maintainability	Follow existing patterns
Cache Wisely	Performance	Cache GET, not mutations; use TTL
Document Decisions	Onboarding	Explain "why" in code comments

---

File Organization

auth/
├── README.md                 (This folder's purpose)
├── RULES.md                  (Data handling rules)
├── FLOWMAP.md                (Application flows)
├── VIEWS.md                  (UI/View patterns)
├── TECH_STACK.md             (Technology versions & usage)
├── ONBOARDING.md             (Getting started & common tasks)
├── INDEX.md                  (This file - navigation guide)
└── auth-universal.js         (Authentication implementation)

---

Version History

Version	Date	Changes
1.0	Jan 2026	Initial comprehensive documentation

---

Last Updated: January 2026
Status: Production Ready
Maintained By: Development Team