# sontivr/secure-ai-blueprint architecture

> Architecture diagram of the GitHub repository sontivr/secure-ai-blueprint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sontivr/secure-ai-blueprint
- Repository: https://github.com/sontivr/secure-ai-blueprint

## Overview

1. **What this repo is**
   - This is a **local-first Secure AI / RAG reference implementation** aimed at regulated environments.
   - The architecture is intentionally small and split into a **UI layer**, an **API/orchestration layer**, and **local AI/storage dependencies**.

2. **User-facing entry points**
   - There are two interactive surfaces:
     - a **FastAPI backend** for programmatic access and API docs
     - a **Streamlit UI** in `backend/app_ui.py` for demo/operator use
   - The README also calls out curl/Swagger-style usage, so the API is the primary system boundary.

3. **Backend application core**
   - `backend/main.py` is the main API composition point.
   - The backend modules are organized around concerns rather than a large monolith:
     - `auth.py` for login/JWT handling
     - `rbac.py` for role checks
     - `rag_pipeline.py` for ingestion and question answering
     - `audit_logger.py` and `logger.py` for operational/audit events
     - `config.py` for runtime settings
     - utility modules for PDF handling, hashing, and redaction

4. **Authentication and authorization boundary**
   - The system uses **JWT authentication** with **role-based access control**.
   - The API exposes protected admin-only paths for ingestion and audit summary, while query access is available to authorized users.
   - `generate_hash.py` and its test suggest local credential/hash handling is part of the security model.

5. **Ingestion pipeline**
   - Admin users submit **text, TXT files, or PDFs** through `/ingest/*`.
   - PDF parsing is isolated in `pdf_utils.py`.
   - Content is then **chunked** and converted into embeddings using **sentence-transformers**, forming the document preparation stage before storage.

6. **Retrieval-augmented generation flow**
   - Query requests hit `/query`.
   - The backend retrieves semantically similar chunks from the local vector store, then sends grounded context to the LLM.
   - The architecture is explicitly **source-grounded**, meaning responses are derived from retrieved documents rather than free-form generation only.

7. **Local AI and storage dependencies**
   - The repo is built around **local infrastructure**:
     - **Ollama** for LLM inference
     - **Chroma** as the vector database with local persistence
   - This means the main data plane stays on the machine/cluster rather than calling external model APIs.

8. **Audit and safety controls**
   - `audit_logger.py` indicates structured event logging for ingestion and query activity.
   - `pii_redactor.py` suggests logs are intended to be sanitized before persistence or reporting.
   - `/audit/summary` provides an admin-facing visibility endpoint over audit events.

9. **Configuration and secrets**
   - Runtime settings are externalized through `.env`-style configuration via `config.py`.
   - The repo includes `.env.example` and Streamlit secrets, reinforcing the boundary between code and environment-specific credentials.
   - This is a deliberate fit for local deployment and regulated-environment reproducibility.

10. **Deployment and infrastructure shape**
   - There is a **Dockerized backend** (`Dockerfile.backend`) and **Kubernetes manifests** under `deploy/k8s/backend`.
   - The K8s layer includes:
     - Deployment, Service, Ingress
     - PVC for persistent local storage
     - Secret template
     - cert-manager issuer config
   - There is also monitoring support via `deploy/k8s/monitoring`, including Grafana ingress and kube-prometheus-stack values.

11. **Operational and delivery flow**
   - `.github/workflows/deploy-backend.yml` and `script/deploy_backend.sh` suggest automated deployment into the target environment.
   - The `docs/` and `architecture/` folders contain design and runbook material, indicating the repo is meant to be understood and operated as a reference implementation, not just run locally.

12. **How to draw the architecture diagram**
   - The clean diagram boundary is:
     - **Clients/UI** on the left
     - **FastAPI secure orchestration layer** in the center
     - **local AI + vector persistence** on the right
     - **audit/config/deployment controls** as supporting layers beneath or around the core
   - The key data paths are:
     - **Login → JWT issuance → protected API calls**
     - **Ingest document → parse/chunk/embed → store in Chroma**
     - **Query → retrieve chunks → send context to Ollama → grounded answer**
     - **Every sensitive action → audit log, with redaction**

Main entry points: [`backend/main.py`](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/main.py) (FastAPI app), [`backend/rag_pipeline.py`](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/rag_pipeline.py) (RAG pipeline), [`backend/audit_logger.py`](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/audit_logger.py) (Audit logger), [`Dockerfile.backend`](https://github.com/sontivr/secure-ai-blueprint/blob/main/Dockerfile.backend) (Backend image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients / UI"]
  node_streamlit_ui["Streamlit UI<br/>operator UI<br/>[app_ui.py]"]
end

subgraph group_api["Secure API"]
  node_fastapi_app["FastAPI app<br/>api entrypoint<br/>[main.py]"]
end

subgraph group_security["Security controls"]
  node_auth["JWT auth<br/>auth module<br/>[auth.py]"]
  node_rbac["RBAC checks<br/>access control<br/>[rbac.py]"]
  node_config["Config<br/>runtime settings<br/>[config.py]"]
  node_hashing["Hash helper<br/>credential utility<br/>[generate_hash.py]"]
end

subgraph group_pipeline["RAG pipeline"]
  node_rag["RAG pipeline<br/>ingest + qa<br/>[rag_pipeline.py]"]
  node_pdf_utils["PDF parser<br/>document parser<br/>[pdf_utils.py]"]
end

subgraph group_observability["Audit / logging"]
  node_audit["Audit logger<br/>audit events<br/>[audit_logger.py]"]
  node_redactor["PII redactor<br/>sanitizer<br/>[pii_redactor.py]"]
  node_logger["App logger<br/>logging setup<br/>[logger.py]"]
end

subgraph group_infra["Local AI / storage"]
  node_ollama[("Ollama<br/>local LLM")]
  node_chroma[("Chroma<br/>vector store")]
  node_embeddings{{"Embeddings<br/>sentence-transformers"}}
end

subgraph group_delivery["Delivery / ops"]
  node_docker_backend["Backend image<br/>container build<br/>[Dockerfile.backend]"]
  node_k8s_backend["K8s backend<br/>deployment manifests<br/>[deployment.yaml]"]
  node_monitoring["Monitoring stack<br/>k8s monitoring"]
  node_deploy_workflow["Deploy workflow<br/>ci/cd<br/>[deploy-backend.yml]"]
end

node_streamlit_ui -->|"uses API"| node_fastapi_app
node_fastapi_app -->|"login/JWT"| node_auth
node_fastapi_app -->|"authorize"| node_rbac
node_fastapi_app -->|"ingest/query"| node_rag
node_fastapi_app -->|"audit"| node_audit
node_fastapi_app -->|"loads settings"| node_config
node_fastapi_app -->|"logs"| node_logger
node_auth -->|"hashes creds"| node_hashing
node_rag -->|"parses PDFs"| node_pdf_utils
node_rag -->|"embeds chunks"| node_embeddings
node_rag -->|"stores/retrieves"| node_chroma
node_rag -->|"generates answers"| node_ollama
node_rag -->|"records events"| node_audit
node_audit -->|"sanitizes"| node_redactor
node_audit -->|"emits"| node_logger
node_docker_backend -->|"packages"| node_fastapi_app
node_k8s_backend -->|"deploys"| node_docker_backend
node_monitoring -.->|"observes"| node_k8s_backend
node_deploy_workflow -->|"applies"| node_k8s_backend
node_deploy_workflow -->|"builds"| node_docker_backend

click node_streamlit_ui "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/app_ui.py"
click node_fastapi_app "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/main.py"
click node_auth "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/auth.py"
click node_rbac "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/rbac.py"
click node_config "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/config.py"
click node_hashing "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/generate_hash.py"
click node_rag "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/rag_pipeline.py"
click node_pdf_utils "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/pdf_utils.py"
click node_audit "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/audit_logger.py"
click node_redactor "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/pii_redactor.py"
click node_logger "https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/logger.py"
click node_docker_backend "https://github.com/sontivr/secure-ai-blueprint/blob/main/Dockerfile.backend"
click node_k8s_backend "https://github.com/sontivr/secure-ai-blueprint/blob/main/deploy/k8s/backend/deployment.yaml"
click node_monitoring "https://github.com/sontivr/secure-ai-blueprint/blob/main/deploy/k8s/monitoring/kube-prometheus-stack-values.yaml"
click node_deploy_workflow "https://github.com/sontivr/secure-ai-blueprint/blob/main/.github/workflows/deploy-backend.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit_ui,node_docker_backend,node_k8s_backend,node_monitoring,node_deploy_workflow toneBlue
class node_fastapi_app toneAmber
class node_auth,node_rbac,node_config,node_hashing toneMint
class node_rag,node_pdf_utils toneRose
class node_audit,node_redactor,node_logger toneIndigo
class node_ollama,node_chroma,node_embeddings toneTeal
```

## Components

### Clients / UI

Interactive entry points for operators and API consumers.

- [Streamlit UI](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/app_ui.py): operator UI · Demo and operator-facing interface. · `backend/app_ui.py`

### Secure API

FastAPI orchestration layer and request boundaries.

- [FastAPI app](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/main.py): api entrypoint · Main API composition and route surface. · `backend/main.py`

### Security controls

Authentication, authorization, and related helpers.

- [JWT auth](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/auth.py): auth module · Login and token issuance/validation. · `backend/auth.py`
- [RBAC checks](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/rbac.py): access control · Role-based authorization gatekeeping. · `backend/rbac.py`
- [Config](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/config.py): runtime settings · Environment-driven application settings. · `backend/config.py`
- [Hash helper](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/generate_hash.py): credential utility · Local hashing helper used in security flows. · `backend/generate_hash.py`

### RAG pipeline

Document ingestion and grounded question answering.

- [RAG pipeline](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/rag_pipeline.py): ingest + qa · Coordinates ingestion, retrieval, and answer generation. · `backend/rag_pipeline.py`
- [PDF parser](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/pdf_utils.py): document parser · Extracts text from PDF inputs for ingestion. · `backend/pdf_utils.py`

### Audit / logging

Operational logging and safety controls.

- [Audit logger](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/audit_logger.py): audit events · Structured logging for sensitive actions. · `backend/audit_logger.py`
- [PII redactor](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/pii_redactor.py): sanitizer · Redacts sensitive content before logging or reporting. · `backend/pii_redactor.py`
- [App logger](https://github.com/sontivr/secure-ai-blueprint/blob/main/backend/logger.py): logging setup · Shared logging configuration and output plumbing. · `backend/logger.py`

### Local AI / storage

Runtime dependencies that stay local to the deployment.

- **Ollama**: local LLM · Local model inference backend for grounded answers.
- **Chroma**: vector store · Persistent local semantic index for chunks and retrieval.
- **Embeddings**: sentence-transformers · Chunk embedding model used during ingestion.

### Delivery / ops

Container, Kubernetes, and automation assets.

- [Backend image](https://github.com/sontivr/secure-ai-blueprint/blob/main/Dockerfile.backend): container build · Container image for backend deployment. · `Dockerfile.backend`
- [K8s backend](https://github.com/sontivr/secure-ai-blueprint/blob/main/deploy/k8s/backend/deployment.yaml): deployment manifests · Deployment, service, ingress, PVC, and secret templates. · `deploy/k8s/backend/deployment.yaml`
- [Monitoring stack](https://github.com/sontivr/secure-ai-blueprint/blob/main/deploy/k8s/monitoring/kube-prometheus-stack-values.yaml): k8s monitoring · Grafana ingress and Prometheus stack values. · `deploy/k8s/monitoring/kube-prometheus-stack-values.yaml`
- [Deploy workflow](https://github.com/sontivr/secure-ai-blueprint/blob/main/.github/workflows/deploy-backend.yml): ci/cd · Automated backend deployment workflow. · `.github/workflows/deploy-backend.yml`

## Connections

- Streamlit UI → FastAPI app: uses API · UI drives the same secured backend surface as API clients.
- FastAPI app → JWT auth: login/JWT · Authentication is handled before protected actions.
- FastAPI app → RBAC checks: authorize · Role checks gate admin and query operations.
- FastAPI app → RAG pipeline: ingest/query · Routes dispatch to the ingestion and question-answering pipeline.
- FastAPI app → Audit logger: audit · Sensitive API activity is recorded for traceability.
- FastAPI app → Config: loads settings · Runtime configuration is sourced from environment settings.
- FastAPI app → App logger: logs · Application logging is initialized through shared logging setup.
- JWT auth → Hash helper: hashes creds · Local hash helper supports credential handling.
- RAG pipeline → PDF parser: parses PDFs · PDF inputs are extracted before chunking and indexing.
- RAG pipeline → Embeddings: embeds chunks · Document chunks are converted into vector representations.
- RAG pipeline → Chroma: stores/retrieves · Embedded chunks are persisted and searched locally.
- RAG pipeline → Ollama: generates answers · Retrieved context is sent to the local LLM for grounded responses.
- RAG pipeline → Audit logger: records events · Ingestion and query actions are written to audit logs.
- Audit logger → PII redactor: sanitizes · PII is removed before audit persistence or summaries.
- Audit logger → App logger: emits · Audit events flow through the shared logging layer.
- Backend image → FastAPI app: packages · The backend service is containerized for deployment.
- K8s backend → Backend image: deploys · Kubernetes manifests run the backend image and expose it.
- Monitoring stack → K8s backend: observes · Monitoring components integrate with the deployed backend.
- Deploy workflow → K8s backend: applies · CI/CD automates backend deployment into the target cluster.
- Deploy workflow → Backend image: builds · Workflow builds the backend container before deployment.
