How guerillamos/documentanalyzer works
Project type and purpose
• This is a full-stack document-analysis application.
• Purpose: Upload a text document in the React UI, call a Python Azure Function to analyze it via Azure OpenAI, persist results in Cosmos DB, then display them back in the UI.
• It’s containerized and runs on Kubernetes locally (Tilt + Traefik) or in Azure.
File structure
• Top level:
• backend/ – Python Azure Functions code, SharedCode utilities, unit tests, containerization (Dockerfile).
• frontend/document-analyzer/ – React SPA with MSAL auth, static assets, NGINX for serving, tests, Dockerfile.
• k8s/ – Kubernetes manifests (secrets, storage, mock-auth).
• certificates/ – OpenSSL config and scripts for local TLS certs.
• helm/ – Traefik Helm values.
• Tiltfile – local-dev orchestration.
• Patterns: serverless (Azure Functions), micro-services style (API and UI are separate containers), cloud-native deployment via K8s.
• Config and deployment artifacts for Tilt, Traefik, K8s, and Docker.
Key architectural notes from the README
• Frontend uses React 18 with MSAL (Azure AD).
• Backend uses Python 3.9+ Azure Functions, Azure OpenAI SDK, Cosmos DB SDK, Azure Identity for auth, retry logic.
• Tilt automates build/deploy to a local K8s cluster with Traefik for ingress and TLS.
• Local certificates are managed via scripts and Kubernetes secrets.
Components
a. Frontend
• React SPA container behind NGINX
• MSAL/Azure AD authentication
b. Ingress & TLS
• Traefik ingress controller with wildcard certs
• Local DNS (*.localhost) routing
c. Backend
• Azure Functions container
• SharedCode modules (JSON helpers, retry logic)
• host.json, function.json, CORS config
d. External/Coud services
• Azure OpenAI (GPT-4)
• Azure Cosmos DB (DocumentAnalysis DB, Results collection)
• Azure AD (token issuance for both UI and Functions)
e. Kubernetes cluster
• Namespaces: traefik, document-analyzer
• Secrets, PVC storage
• Tilt orchestration (Tiltfile)
f. Local tooling
• Tilt
• Docker Desktop Kubernetes
• OpenSSL certificate generation
Interactions & data flow
1. User → React UI (HTTPS)
2. React UI → MSAL → Azure AD (token)
3. React UI → API call (HTTPS) → Traefik → Azure Functions
4. Function handler uses Azure Identity to get credentials → calls Azure OpenAI
5. Azure OpenAI returns analysis JSON → Function transforms via json_helpers
6. Function writes results to Cosmos DB
7. Function returns processed data to React UI
8. React displays analysis results (tabs, charts, lists)
Architectural patterns and design principles
• Separation of concerns: UI vs API vs storage
• Serverless Functions for event-driven compute
• Retry with exponential backoff for resilience
• OAuth2/OpenID Connect via MSAL/Azure AD
• Containerization + K8s for portability and consistency
• Infrastructure as code: Tilt, Helm, Kubernetes YAML