# Auth Folder Documentation Index

**All enforcement rules, patterns, and guidance for Job Info**

---

## 📚 Documentation Files

### For First-Time Setup & Questions
- **[ONBOARDING.md](./ONBOARDING.md)** ← **START HERE**
  - Quick start (5 minutes)
  - Project structure overview
  - Common tasks
  - Debugging tips
  - FAQ

### Core Rules & Patterns
- **[RULES.md](./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](./FLOWMAP.md)**
  - High-level user journey
  - Data flow diagram
  - Cache flow
  - State management flow
  - Authentication flow
  - View hierarchy

- **[VIEWS.md](./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](./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](./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](./ONBOARDING.md)
2. Set up dev environment (5 min)
3. Read [RULES.md](./RULES.md) (30 min)

### "I need to add a new API endpoint"
1. Check [RULES.md](./RULES.md) - Cache Strategy
2. Check [TECH_STACK.md](./TECH_STACK.md) - Hono Patterns
3. Follow [ONBOARDING.md](./ONBOARDING.md) - Adding New Endpoint

### "I need to create a new view/page"
1. Check [VIEWS.md](./VIEWS.md) - View Architecture
2. Check [FLOWMAP.md](./FLOWMAP.md) - User Flow
3. Follow [ONBOARDING.md](./ONBOARDING.md) - Adding New View

### "I need to understand how data flows"
1. Read [FLOWMAP.md](./FLOWMAP.md) - Data Flow Diagram
2. Check [RULES.md](./RULES.md) - Caching Strategy
3. Review [TECH_STACK.md](./TECH_STACK.md) - ioredis Usage

### "I'm stuck or debugging an error"
1. Check [ONBOARDING.md](./ONBOARDING.md) - Debugging section
2. Review [RULES.md](./RULES.md) - Error Handling
3. Search logs in `logs/` folder

### "I need to modify auth behavior"
1. Review [auth-universal.js](./auth-universal.js)
2. Check [RULES.md](./RULES.md) - Authentication & Token Rules
3. Test in [ONBOARDING.md](./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