# vinaykumarvk/create_ekg architecture

> Architecture diagram of the GitHub repository vinaykumarvk/create_ekg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinaykumarvk/create_ekg
- Repository: https://github.com/vinaykumarvk/create_ekg

## Overview

This is a **single-service FastAPI web application** that serves a **secure admin console** for managing an **OpenAI Vector Store**. Admins authenticate, then can:
- Upload local documents (validated and size-limited)
- Optionally browse/import files from a **Google Drive folder** via service account
- Trigger **vector store orchestration** (create store if missing, upload files to OpenAI Files API, re-embed/replace stale embeddings)

So the “system” is not a microservice mesh; it’s a **hardened admin web app** with a few critical integrations: **OpenAI APIs** and optional **Google Drive APIs**.

##### Core service boundary
- `api/main.py`: **FastAPI app**, routes, middleware, security headers, request lifecycle
- `api/settings.py`: **Config** (env-driven dataclasses, secrets, feature flags like Drive enablement)
- `api/security.py`: **Auth primitives** (PBKDF2 password verification, CSRF helpers)
- `api/session.py`: **Session + flash messaging** (secure cookie/session)
- `api/vector_store.py`: **OpenAI orchestration layer** (vector store creation/lookup, file ingestion, stale removal)
- `api/google_drive.py`: **Google Drive integration** (folder listing, downloading file content)
- `api/templates/*`: **Server-rendered UI** (Jinja2: login + dashboard)
- `api/static/*`: **Front-end assets** (CSS, admin JS)
- `api/compat.py`: compatibility helpers (likely small glue—don’t over-emphasize unless it’s central)

##### Infra / packaging / deployment
- `Dockerfile`, `start.sh`: container runtime entry + startup
- `cloudbuild.yaml`: CI/CD build pipeline (Google Cloud Build implied)
- `requirements.txt`, `pyproject.toml`: dependency and packaging metadata

##### What the README adds (runtime behaviors worth diagramming)
The README tells you key runtime concerns to explicitly represent:

**Security perimeter**
- PBKDF2 password hash verification
- CSRF protection
- Secure session cookies
- Defensive HTTP headers

**Document ingestion constraints**
- Reject empty uploads
- Max 100MB
- Allowed types list (PDF/TXT/MD/DOCX/CSV/JSON)

**OpenAI vector store lifecycle**
- Create vector store if needed
- Remove stale embeddings
- Re-ingest updated documents via OpenAI Files API

**Google Drive is optional**
- Service account file and (optional) impersonated user
- Browser/import from Drive folder inside dashboard

##### Client / UI
- Admin’s Browser
- Server-rendered pages (Jinja2 templates)
- Static assets (CSS/JS)

##### Application (FastAPI Service)
Split into internal modules (separating into more components is better here):
- Routing / Controllers (`api/main.py`)
- AuthN/AuthZ + CSRF (`api/security.py`)
- Session & flash (`api/session.py`)
- Vector Store Orchestrator (`api/vector_store.py`)
- Google Drive Connector (`api/google_drive.py`, optional)
- Configuration (`api/settings.py`)

##### External Systems
- OpenAI API
- Files API
- Vector Store API (or “Vector Store endpoint”)
- Google Drive API (optional)

**Flow 1: Login**
Browser → FastAPI `/login`
FastAPI → Security: verify PBKDF2 hash
FastAPI → Session: set secure session cookie
FastAPI → Browser: redirect to dashboard

**Flow 2: Local upload → ingestion**
Browser (multipart upload) → FastAPI `/upload`
FastAPI → Document Validation (size/type/empty)
FastAPI → Vector Store Orchestrator
Vector Store Orchestrator → OpenAI Files API (upload)
Vector Store Orchestrator → OpenAI Vector Store (attach file / re-embed / delete stale)
Result → FastAPI → Browser (dashboard status / flash message)

**Flow 3: Google Drive browse/import (optional branch)**
Browser → FastAPI `/drive/browse` (or similar)
FastAPI → Google Drive Connector → Google Drive API (list)
Browser selects file → FastAPI `/drive/import`
FastAPI → Google Drive Connector → Google Drive API (download)
Downloaded bytes → Document Validation → Vector Store Orchestrator → OpenAI APIs

**Flow 4: Vector store bootstrap**
On first use (or startup), Orchestrator:
FastAPI/Orchestrator → OpenAI Vector Store API: create/lookup store (controlled by `OPENAI_VECTOR_STORE_ID`)

##### Configuration/secrets as a first-class node
- session secret
- admin username/password hash
- OpenAI key + vector store id
- Google service account + impersonation user

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — Context/Container
  %% =========================
  subgraph "Context / Container View (Single FastAPI Service)"
    direction TB

    Admin["Admin Browser"]:::client

    subgraph "Create EKG Admin Console (FastAPI Web App)"
      direction TB
      WebUI["Server-rendered UI (Jinja2 templates)"]:::ui
      WebStatic["Static assets (CSS/JS)"]:::ui
      FastAPI["FastAPI app (routes + middleware)"]:::service
      WebUI -->|"HTML"| Admin
      WebStatic -->|"CSS/JS"| Admin
      Admin -->|"HTTP(S) GET/POST"| FastAPI
      FastAPI -->|"HTML + redirects"| Admin
    end

    Env["Environment / .env (secrets + feature flags)"]:::config

    subgraph "External Systems"
      direction TB
      OpenAI["OpenAI API"]:::external
      OpenAIFiles["Files API"]:::external
      OpenAIVS["Vector Store API"]:::external
      GDrive["Google Drive API (optional)"]:::external

      OpenAI -->|"includes"| OpenAIFiles
      OpenAI -->|"includes"| OpenAIVS
    end

    Env -->|"configures"| FastAPI

    %% Major flows (high-level)
    Admin -->|"Login: credentials + CSRF token"| FastAPI
    Admin -->|"Local upload: multipart bytes"| FastAPI
    Admin -->|"Drive browse/import (optional)"| FastAPI

    FastAPI -->|"upload files + manage embeddings"| OpenAIFiles
    FastAPI -->|"create/lookup vector store"| OpenAIVS
    FastAPI -.->|"list/download files (optional)"| GDrive
  end

  %% =========================
  %% Diagram 2 — Component View (Inside FastAPI)
  %% =========================
  subgraph "Component View (Inside FastAPI Service)"
    direction TB

    subgraph "Request Perimeter (Cross-cutting Security)"
      direction TB
      Middleware["Middleware + Security Headers + CSRF gate"]:::security
      Sec["api/security.py (PBKDF2 verify + CSRF helpers)"]:::security
      Sess["api/session.py (secure session cookie + flash messaging)"]:::security
      Middleware -->|"uses"| Sec
      Middleware -->|"uses"| Sess
    end

    subgraph "Routing / Controllers"
      direction TB
      Main["api/main.py (routes + request lifecycle)"]:::service
      Templates["Jinja2 templates (login + dashboard + layout)"]:::ui
      Static["Static files (CSS/JS)"]:::ui
      Compat["api/compat.py (compat/glue)"]:::internal

      Main -->|"render"| Templates
      Main -->|"serves"| Static
      Main -->|"helpers"| Compat
    end

    subgraph "Core Business Logic"
      direction TB
      Validate["Document Validation (size/type/empty checks)"]:::internal
      VS["api/vector_store.py (OpenAI vector store orchestration)"]:::internal
      Drive["api/google_drive.py (Drive connector, optional)"]:::internal
      Settings["api/settings.py (env-driven settings + secrets + flags)"]:::config
    end

    %% Internal wiring
    Settings -->|"feature flags + secrets"| Main
    Settings -->|"OpenAI key + vector_store_id"| VS
    Settings -.->|"Drive enablement + SA creds"| Drive

    Main -->|"all requests pass"| Middleware

    %% Flow 1: Login
    Middleware -->|"auth flow"| Sec
    Sec -->|"verify PBKDF2"| Main
    Main -->|"set session + flash"| Sess
    Sess -->|"session cookie"| Main
    Main -->|"redirect dashboard"| Templates

    %% Flow 2: Local upload -> ingestion
    Main -->|"multipart bytes"| Validate
    Validate -->|"validated bytes + filename"| VS
    VS -->|"file upload"| OpenAIFiles
    VS -->|"create/lookup store"| OpenAIVS
    VS -->|"attach/re-embed/delete stale"| OpenAIVS
    VS -->|"status + ids"| Main
    Main -->|"flash status"| Sess
    Main -->|"dashboard view"| Templates

    %% Flow 3: Google Drive browse/import (optional)
    Main -.->|"browse folder (optional)"| Drive
    Drive -.->|"list files"| GDrive
    Main -.->|"import selection (optional)"| Drive
    Drive -.->|"download bytes"| GDrive
    Drive -.->|"file bytes"| Validate
  end

  %% =========================
  %% Packaging/infra nodes (kept vertical and separate)
  %% =========================
  subgraph "Build / Deploy / Quality (Non-runtime)"
    direction TB
    Docker["Container build (Dockerfile)"]:::infra
    Start["Startup entrypoint (start.sh)"]:::infra
    CloudBuild["CI/CD (cloudbuild.yaml)"]:::infra
    Req["Dependencies (requirements.txt)"]:::infra
    PyProj["Packaging (pyproject.toml)"]:::infra
    Tests["Unit tests (tests/test_utils.py)"]:::quality

    CloudBuild -->|"builds"| Docker
    Docker -->|"runs"| Start
    Req -->|"installs"| Docker
    PyProj -->|"metadata"| Docker
    Tests -->|"verifies"| Main
  end

  %% =========================
  %% Click events (component_mapping)
  %% =========================
  click Main "https://github.com/vinaykumarvk/create_ekg/blob/main/api/main.py"
  click Settings "https://github.com/vinaykumarvk/create_ekg/blob/main/api/settings.py"
  click Sec "https://github.com/vinaykumarvk/create_ekg/blob/main/api/security.py"
  click Sess "https://github.com/vinaykumarvk/create_ekg/blob/main/api/session.py"
  click VS "https://github.com/vinaykumarvk/create_ekg/blob/main/api/vector_store.py"
  click Drive "https://github.com/vinaykumarvk/create_ekg/blob/main/api/google_drive.py"
  click Compat "https://github.com/vinaykumarvk/create_ekg/blob/main/api/compat.py"
  click Templates "https://github.com/vinaykumarvk/create_ekg/blob/main/api/templates/layout.html"
  click Static "https://github.com/vinaykumarvk/create_ekg/blob/main/api/static/js/admin.js"

  click Docker "https://github.com/vinaykumarvk/create_ekg/tree/main/Dockerfile"
  click Start "https://github.com/vinaykumarvk/create_ekg/blob/main/start.sh"
  click CloudBuild "https://github.com/vinaykumarvk/create_ekg/blob/main/cloudbuild.yaml"
  click Req "https://github.com/vinaykumarvk/create_ekg/blob/main/requirements.txt"
  click PyProj "https://github.com/vinaykumarvk/create_ekg/blob/main/pyproject.toml"
  click Tests "https://github.com/vinaykumarvk/create_ekg/blob/main/tests/test_utils.py"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#E8F1FF,stroke:#2B5DB6,stroke-width:1.5px,color:#0B1B3A
  classDef service fill:#E9FFF2,stroke:#1B7F3A,stroke-width:1.5px,color:#0A2A14
  classDef internal fill:#F2FFEE,stroke:#2A9D4B,stroke-width:1.2px,color:#0A2A14
  classDef ui fill:#FFF4E6,stroke:#B26A00,stroke-width:1.5px,color:#3A2200
  classDef security fill:#FFECEC,stroke:#B3261E,stroke-width:1.8px,color:#3A0B0B
  classDef external fill:#F1F1F1,stroke:#444,stroke-width:1.5px,color:#111
  classDef config fill:#F3E8FF,stroke:#6B21A8,stroke-width:1.5px,color:#1F0A33
  classDef infra fill:#E6FFFB,stroke:#0F766E,stroke-width:1.5px,color:#062B28
  classDef quality fill:#FFF7ED,stroke:#9A3412,stroke-width:1.5px,color:#3A1408
```
