175 lines
6.2 KiB
Markdown
175 lines
6.2 KiB
Markdown
# 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](./INDEX.md) - Task-based navigation
|
|
- **Getting started:** [ONBOARDING.md](./ONBOARDING.md) - 5-minute quick start
|
|
- **Core rules:** [RULES.md](./RULES.md) - **MOST IMPORTANT** - Read first
|
|
- **Visual diagrams:** [FLOWMAP.md](./FLOWMAP.md) - Application flows
|
|
- **UI patterns:** [VIEWS.md](./VIEWS.md) - View architecture
|
|
- **Tech stack:** [TECH_STACK.md](./TECH_STACK.md) - Technology versions
|
|
|
|
### Summary
|
|
- **Overview:** [DOCUMENTATION_SUMMARY.md](./DOCUMENTATION_SUMMARY.md) - What was created
|
|
|
|
### Implementation
|
|
- **Auth code:** [auth-universal.js](./auth-universal.js) - Single PocketBase auth
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### For New Developers
|
|
1. Read [INDEX.md](./INDEX.md) (2 min)
|
|
2. Follow [ONBOARDING.md](./ONBOARDING.md) (15 min)
|
|
3. Study [RULES.md](./RULES.md) (30 min)
|
|
|
|
### For Specific Tasks
|
|
- Check [INDEX.md](./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](./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](./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. |