v1.0.0-alpha4: Add Redis/Valkey caching and search with principal agent auth for global settings

2026-01-01 23:58:00 +00:00
parent f98ff8fcec
commit 71e5070e6c
10 changed files with 1012 additions and 6 deletions
@@ -8,6 +8,69 @@ ACTIVE_LOGIN_METHOD=pb-oauth-via-microsoft

 ---

+## Environment Variables
+
+### Required Variables
+
+**Azure AD / Microsoft Authentication:**
+- `CLIENT_ID` - Azure AD Application Client ID
+- `CLIENT_SECRET` - Azure AD Application Client Secret
+- `TENANT_ID` - Azure AD Tenant ID
+- `REDIRECT_URI` - OAuth redirect URI
+
+**PocketBase:**
+- `PB_DB` - PocketBase database URL (e.g., `https://pocketbase.ccllc.pro`)
+- `PB_COLLECTION` - Collection name for job data (e.g., `Job_Info_TestEnv`)
+- `PB_AUTH_COLLECTION` - Collection name for user authentication (e.g., `Users`)
+
+**Redis/Valkey (Caching & Search):**
+- `REDIS_URL` - Redis/Valkey connection URL (e.g., `redis://localhost:6379` or `redis://redis-server:6379`)
+  - If not provided, defaults to `redis://localhost:6379`
+  - For production, connect to the same Redis/Valkey instance as Job-Info-Prod
+
+**Optional:**
+- `PORT` - Server port (default: 3025)
+
+---
+
+## Caching & Search
+
+This application uses Redis/Valkey for:
+
+1. **Data Caching**: Job records are cached for 5 minutes (300 seconds) to reduce PocketBase queries
+2. **Search Results Caching**: Search results are cached for 3 minutes (180 seconds)
+3. **Cache Invalidation**: Automatically clears cache when data is updated
+
+### API Endpoints
+
+**Get All Jobs (with caching):**
+```
+GET /api/jobs
+Headers: X-PocketBase-Token: <user_token>
+```
+
+**Search Jobs (with caching):**
+```
+GET /api/jobs/search?q=<query>
+Headers: X-PocketBase-Token: <user_token>
+```
+Searches across: Job_Number, Job_Full_Name, Job_Name, Company_Client, Contact_Person, Estimator, Job_Status, Project_Manager, Notes
+
+**Clear Cache (admin):**
+```
+POST /api/cache/clear
+Headers: X-PocketBase-Token: <user_token>
+```
+
+### Cache Strategy
+
+- **Source of Truth**: PocketBase remains the source of truth for updates
+- **Read Operations**: Check cache first, fallback to PocketBase if cache miss
+- **Write Operations**: Update PocketBase, then invalidate cache
+- **Future**: Will switch to Job-Info-Prod for production data synchronization
+
+---
+
 ## Shared Rules (All Methods)
 - Serve frontend from the project’s `frontend` folder; show login UI only when not authenticated.
 - Secrets come from `.env`; never hardcode or log secrets/tokens.