93 lines
10 KiB
Markdown
93 lines
10 KiB
Markdown
---
|
||
title: "Tech Patterns Index"
|
||
description: "Recurring technology stacks across Oliver Agency projects"
|
||
tags: [index, tech-patterns]
|
||
created: 2026-04-15
|
||
updated: 2026-05-01
|
||
---
|
||
|
||
# Tech Patterns
|
||
|
||
Recurring technology stacks used across Oliver Agency projects. Each article covers a specific pattern with projects, gotchas, and code examples.
|
||
|
||
## Patterns
|
||
|
||
| Pattern | Description | Projects |
|
||
|---------|-------------|---------|
|
||
| [[wiki/tech-patterns/fastapi-python-docker\|fastapi-python-docker]] | FastAPI + Python + Docker — dominant backend stack | GMAL, Mod Comms, Video Accessibility, OliVAS, PIMCO, Solventum, Enterprise Nexus |
|
||
| [[wiki/tech-patterns/react-vite-typescript\|react-vite-typescript]] | React + Vite + TypeScript — standard Oliver SPA frontend | GMAL, Mod Comms, Semblance, Video Accessibility, LUSA, Build-A-Squad, BAIC |
|
||
| [[wiki/tech-patterns/nextjs-fastapi-fullstack\|nextjs-fastapi-fullstack]] | Next.js + FastAPI — for complex multi-service AI platforms | Enterprise Nexus, Sandbox NotebookLM, Oliver AI Bot 2.0, DeckForge |
|
||
| [[wiki/tech-patterns/azure-ad-msal-auth\|azure-ad-msal-auth]] | Azure AD / MSAL SSO — Oliver internal auth standard | GMAL, Enterprise Nexus, Cinema Studio Pro, Mod Comms, BAIC, Sandbox |
|
||
| [[wiki/tech-patterns/python-ai-agents\|python-ai-agents]] | Claude / Gemini / OpenAI / LlamaIndex integration patterns | GMAL, Mod Comms, Semblance, OliVAS, PIMCO, Video Accessibility, Enterprise Nexus |
|
||
| [[wiki/tech-patterns/redis-celery-worker-queue\|redis-celery-worker-queue]] | Redis + Celery for async long-running tasks | Enterprise Nexus, Video Accessibility, PDF Accessibility |
|
||
| [[wiki/tech-patterns/box-api-integration\|box-api-integration]] | Box API for client asset workflows | Ford QC, Ford SFTP, L'Oréal, Ferrero |
|
||
| [[wiki/tech-patterns/one2edit-api\|one2edit-api]] | One2Edit translation platform API | 3M Portal, H&M O2E Tool |
|
||
| [[wiki/tech-patterns/nodejs-vanilla-proxy\|nodejs-vanilla-proxy]] | Node.js + Vanilla JS lightweight proxy tools | 3M Portal, Ferrero, Homepage |
|
||
| [[wiki/tech-patterns/kling-veo-video-api\|kling-veo-video-api]] | Kling AI + Google Veo 3.1 video generation — camera control, I2V, polling | Cinema Studio Pro |
|
||
| [[wiki/tech-patterns/cost-tracker-integration\|cost-tracker-integration]] | **Connect any project to ai-cost-tracker**: API key → httpx client → preflight/record pattern → budgets. Live at `optical-dev.oliver.solutions/cost-tracker/` | All Oliver projects |
|
||
| [[wiki/tech-patterns/cost-tracker-pricing-sources\|cost-tracker-pricing-sources]] | Three-layer pricing: LiteLLM auto-sync > YAML (non-LLM) > admin override; historical `effective_from/to` | ai-cost-tracker |
|
||
| [[wiki/tech-patterns/cost-tracker-providers\|cost-tracker-providers]] | Billing units per provider: Gemini `usage_metadata` tokens, ElevenLabs/GCP TTS `len(text)` chars | All AI projects |
|
||
| [[wiki/tech-patterns/runtime-credential-rotation-admin-panel\|Runtime Credential Rotation with Admin Panel]] | When you need to allow administrators to update time-sensitive API credentials (like monthly token r | — |
|
||
| [[wiki/tech-patterns/xss-validation-false-positive-word-boundary\|Fixing XSS Validation False Positives in JSON Field Names]] | When a content security middleware rejects legitimate JSON payloads with "400 Bad Request" errors, a | — |
|
||
| [[wiki/tech-patterns/apache-spa-proxy-configuration-with-includes\|Apache SPA + API Proxy Configuration via Includes]] | When deploying a Single Page Application (SPA) alongside a backend API on the same Apache server, bu | — |
|
||
| [[wiki/tech-patterns/azure-sso-pkce-browser-token-exchange\|Azure SSO with MSAL: Browser-Based Token Exchange Pattern]] | When implementing Single Page Application (SPA) authentication with Azure AD where the frontend hand | — |
|
||
| [[wiki/tech-patterns/docker-volume-mounts-for-development-changes\|Docker Volume Mounts for Development: Avoiding Baked Code Issues]] | When deploying applications in Docker containers where code or configuration changes need to be refl | — |
|
||
| [[wiki/tech-patterns/websocket-keepalive-terminal-close\|WebSocket Keepalive + Terminal Close Codes]] | Bidirectional 20s keepalive + terminal close codes (4001/4003/4004/4403) to prevent reconnect storms through Apache mod_proxy_wstunnel | video-accessibility, mod-comms |
|
||
| [[wiki/tech-patterns/pydantic-empty-string-coercion\|Pydantic Empty String → None Coercion]] | field_validator with mode='before' to treat "" as absent optional field — prevents 400 on CC-only or AD-only payloads | video-accessibility |
|
||
| [[wiki/tech-patterns/vtt-descriptive-transcript-regeneration\|VTT Edit → Descriptive Transcript Regeneration]] | Pattern for keeping descriptive_transcript.txt in sync when captions or AD VTTs are edited via PATCH /vtt | video-accessibility |
|
||
| [[wiki/tech-patterns/git-worktrees-parallel-claude-sessions\|Using Git Worktrees for Parallel Claude Development Sessions]] | Use git worktrees when you need to run multiple independent Claude sessions simultaneously on differ | — |
|
||
| [[wiki/tech-patterns/public-share-link-review\|Public Share-Link Review Pattern]] | Signed-token public endpoint for client approve/reject without login — HMAC token, 409 double-submit guard, conditional UI buttons | — |
|
||
| [[wiki/tech-patterns/azure-ad-sso-migration-user-isolation\|Azure AD SSO Integration with User Isolation]] | When migrating an existing application from local authentication to Azure AD Single Sign-On (SSO), r | — |
|
||
| [[wiki/tech-patterns/recovering-corrupted-caption-metadata-after-failed-translations\|Recovering Corrupted Caption Metadata After Failed Translations]] | When VTT caption files exist in cloud storage (GCS) but their URI references have been deleted from | — |
|
||
| [[wiki/tech-patterns/gemini-models\|Gemini API Models Reference]] | Все API-идентификаторы Gemini 3.x и 2.5: text, TTS, image, live. Таблица точных `model=` строк для API вызовов + предупреждение про несуществующий `gemini-3.1-flash-preview` | video-accessibility, all AI projects |
|
||
| [[wiki/tech-patterns/adaptive-rate-limit-backoff-strategy\|Adaptive Rate Limit Backoff with API Retry-After Headers]] | When integrating with third-party APIs that enforce rate limits (429 responses) and return dynamic r | — |
|
||
| [[wiki/tech-patterns/omg-api\|OMG Platform REST API]] | Oliver internal marketing ops REST API (v2) — briefs, deliverables, tasks, users; TYK gateway + X-Api-Key auth; RFC 7807 errors | Ferrero, 3M OMG Portal |
|
||
| [[wiki/tech-patterns/omg-api 2\|OMG Platform REST API]] | REST API for the **OMG marketing operations platform** (Oliver internal). Manages briefs, deliverabl | raw/Scalar API Reference.md |
|
||
| [[wiki/tech-patterns/docker-compose-systemd-auto-restart\|Docker Compose Auto-Restart with Systemd Service]] | When a Docker Compose application (like a multi-container stack) needs to automatically restart afte | — |
|
||
| [[wiki/tech-patterns/payload-cms-access-control-overview\|Payload CMS — Access Control Overview]] | Three access control types (Collection/Global/Field), default auth guard, Admin Panel sync via Access Operation, locale-specific access, Where query row-level security | — |
|
||
| [[wiki/tech-patterns/payload-cms-installation\|Payload CMS — Installation & Setup]] | TypeScript-first headless CMS running inside Next.js App Router — install, `withPayload`, `payload.config.ts`, DB adapters | — |
|
||
| [[wiki/tech-patterns/payload-cms-collection-access-control\|Payload CMS — Collection Access Control]] | Per-operation access functions (`create`/`read`/`update`/`delete`/`admin`/`unlock`/`readVersions`); boolean or Query return for row-level security | — |
|
||
| [[wiki/tech-patterns/payload-cms-field-access-control\|Payload CMS — Field-Level Access Control]] | `access.create/read/update` per field — boolean only (no Query), silent discard on deny, `read:false` omits key from response | — |
|
||
| [[wiki/tech-patterns/payload-cms-globals-access-control\|Payload CMS — Globals Access Control]] | `read`/`update`/`readVersions` on Global configs — boolean or Query return; `readVersions` constraint targets versions collection not the Global | — |
|
||
| [[wiki/tech-patterns/payload-cms-admin-accessibility\|Payload CMS — Admin Panel Accessibility]] | WCAG 2.2 AA in-progress; Axe in e2e, keyboard nav + screen reader manual testing; report issues via GitHub Discussion | — |
|
||
| [[wiki/tech-patterns/payload-cms-admin-panel-location\|Payload CMS — Custom Admin Panel Location]] | Move `/admin` to any route, nest `(payload)` deeper, co-locate with custom dashboards; importMap config, layout.tsx safety, troubleshooting | — |
|
||
| [[wiki/tech-patterns/payload-cms-customizing-css\|Payload CMS — Customizing CSS & SCSS]] | Global stylesheet, CSS layers (`@layer payload-default`), BEM class targeting, CSS variable overrides for colors/sizing/elevation, dark mode | — |
|
||
| [[wiki/tech-patterns/payload-cms-locked-documents\|Payload CMS — Document Locking]] | Concurrency lock per document — auto-expires after 300s, take-over UX, `overrideLock` flag for API bypasses | — |
|
||
| [[wiki/tech-patterns/payload-cms-admin-metadata\|Payload CMS — Admin Panel Metadata]] | Four-level cascade (Root→Collection/Global→View), `titleSuffix`, `defaultOGImageType`, icons, OG, robots — all via Next.js `generateMetadata` | — |
|
||
|
||
## Quick Decision Guide
|
||
|
||
```
|
||
New project → what stack?
|
||
├── Complex AI platform, multi-user → nextjs-fastapi-fullstack
|
||
├── Standard tool with UI → fastapi-python-docker + react-vite-typescript
|
||
├── Simple client portal / proxy → nodejs-vanilla-proxy
|
||
├── Static page, no backend → plain HTML/JS
|
||
└── Needs auth? → azure-ad-msal-auth
|
||
└── Has AI calls? → always add cost-tracker-integration
|
||
```
|
||
|
||
## Cost Tracker Quick Reference
|
||
|
||
Every new Oliver project that makes AI API calls should integrate the cost tracker.
|
||
|
||
**Admin UI:** `https://optical-dev.oliver.solutions/cost-tracker/`
|
||
|
||
**Minimum integration (3 env vars + 2 HTTP calls):**
|
||
|
||
```env
|
||
COST_TRACKER_BASE_URL=https://optical-dev.oliver.solutions/cost-tracker/v1
|
||
COST_TRACKER_API_KEY=ct_live_xxx
|
||
COST_TRACKER_SOURCE_APP=my-project
|
||
```
|
||
|
||
```python
|
||
# Before AI call
|
||
r = await ct.post("/preflight", json={...})
|
||
if not r.json()["allow"]: raise BudgetExceeded()
|
||
|
||
# After AI call
|
||
await ct.post("/usage/record", json={...})
|
||
```
|
||
|
||
See [[wiki/tech-patterns/cost-tracker-integration|cost-tracker-integration]] for the full 9-step guide.
|