# guerillamos/documentanalyzer architecture

> Architecture diagram of the GitHub repository guerillamos/documentanalyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guerillamos/documentanalyzer
- Repository: https://github.com/guerillamos/documentanalyzer

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Browser
    subgraph "User Interaction"
        User["User"]:::external
        Browser["Browser"]:::external
    end

    User -->|"interacts via HTTPS"| Browser

    %% Frontend Namespace
    subgraph "document-analyzer Namespace"
        direction TB
        subgraph "Frontend" 
            direction TB
            NGINX["NGINX Server"]:::frontend
            ReactSPA["React SPA"]:::frontend
        end

        Browser -->|"HTTPS"| NGINX
        NGINX -->|"serves SPA"| ReactSPA

        %% Frontend click events
        click FrontendDocker "https://github.com/guerillamos/documentanalyzer/tree/main/frontend/document-analyzer/Dockerfile"
        click NginxConf "https://github.com/guerillamos/documentanalyzer/blob/main/frontend/document-analyzer/nginx.conf"
        click ReactSrc "https://github.com/guerillamos/documentanalyzer/tree/main/frontend/document-analyzer/src/"
        click EntryPoint "https://github.com/guerillamos/documentanalyzer/blob/main/frontend/document-analyzer/src/index.js"
        click AppJS "https://github.com/guerillamos/documentanalyzer/blob/main/frontend/document-analyzer/src/App.js"
        click ComponentsDir "https://github.com/guerillamos/documentanalyzer/tree/main/frontend/document-analyzer/src/components/"
        click TestsFront "https://github.com/guerillamos/documentanalyzer/tree/main/frontend/document-analyzer/src/components/__tests__/"
    end

    %% Ingress & TLS Namespace
    subgraph "traefik Namespace"
        direction TB
        Traefik["Traefik Ingress Controller"]:::infra
        Certs["TLS Certificates"]:::infra
    end

    ReactSPA -->|"POST /analyze (HTTPS)"| Traefik
    Certs --> Traefik

    click TraefikHelm "https://github.com/guerillamos/documentanalyzer/blob/main/helm/traefik.yaml"
    click CertsDir "https://github.com/guerillamos/documentanalyzer/tree/main/certificates/"

    %% Backend Namespace
    subgraph "document-analyzer Namespace"
        direction TB
        subgraph "Backend (Azure Functions)"
            direction TB
            FunctionContainer["Functions Container"]:::backend
            SharedCode["SharedCode Utilities"]:::backend
        end
    end

    Traefik -->|"routes to Functions"| FunctionContainer
    FunctionContainer -->|"uses Azure Identity SDK"| AzureAD
    FunctionContainer -->|"SDK call"| OpenAI
    OpenAI -->|"returns JSON"| FunctionContainer
    FunctionContainer -->|"transforms via json_helpers"| SharedCode
    FunctionContainer -->|"writes results"| CosmosDB
    FunctionContainer -->|"responds JSON"| Traefik

    %% Backend click events
    click BackendDocker "https://github.com/guerillamos/documentanalyzer/tree/main/backend/Dockerfile"
    click Requirements "https://github.com/guerillamos/documentanalyzer/blob/main/backend/requirements.txt"
    click FunctionJson "https://github.com/guerillamos/documentanalyzer/blob/main/backend/AnalysisFunction/function.json"
    click FunctionCors "https://github.com/guerillamos/documentanalyzer/blob/main/backend/AnalysisFunction/function.cors.json"
    click HostConfig "https://github.com/guerillamos/documentanalyzer/blob/main/backend/host.json"
    click JsonHelpers "https://github.com/guerillamos/documentanalyzer/blob/main/backend/SharedCode/json_helpers.py"
    click RetryHelpers "https://github.com/guerillamos/documentanalyzer/blob/main/backend/SharedCode/retry_helpers.py"
    click BackendTests "https://github.com/guerillamos/documentanalyzer/tree/main/backend/tests/"

    %% External Cloud Services
    subgraph "Azure Cloud" 
        direction TB
        AzureAD["Azure AD (OAuth2)"]:::external
        OpenAI["Azure OpenAI (GPT-4)"]:::external
        CosmosDB["Azure Cosmos DB"]:::external
    end

    Browser -->|"GET token via MSAL"| AzureAD
    FunctionContainer -->|"token request"| AzureAD
    OpenAI --> AzureAD

    %% Infrastructure
    subgraph "Local Dev Environment" 
        direction TB
        Kubernetes["Kubernetes Cluster"]:::infra
        Tilt["Tilt"]:::infra
    end

    Tilt --> Kubernetes
    Traefik --> Kubernetes
    FunctionContainer --> Kubernetes
    NGINX --> Kubernetes

    click MockAuth "https://github.com/guerillamos/documentanalyzer/blob/main/k8s/mock-auth-secrets.yaml"
    click ProductionSecrets "https://github.com/guerillamos/documentanalyzer/blob/main/k8s/secrets.yaml"
    click StorageYaml "https://github.com/guerillamos/documentanalyzer/blob/main/k8s/storage.yaml"
    click Tiltfile "https://github.com/guerillamos/documentanalyzer/tree/main/Tiltfile"

    %% Sample Test Document
    TestDoc["test-document.txt"]:::infra
    User -->|"uploads sample"| TestDoc
    TestDoc --> Browser

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px
    classDef backend fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef infra fill:#eeeeee,stroke:#616161,stroke-width:2px
    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    class user_ext external
    class User user_ext
    class Browser user_ext
```
