209 lines
5.8 KiB
Markdown
209 lines
5.8 KiB
Markdown
# 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
|