How sontivr/secure-ai-blueprint works
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: main.py FastAPI app · rag_pipeline.py RAG pipeline · audit_logger.py Audit logger · Dockerfile.backend Backend image
Components 18
Clients / UI
Interactive entry points for operators and API consumers.
- Streamlit UI · Demo and operator-facing interface.
backend/app_ui.py
Secure API
FastAPI orchestration layer and request boundaries.
- FastAPI app · Main API composition and route surface.
backend/main.py
Security controls
Authentication, authorization, and related helpers.
- JWT auth · Login and token issuance/validation.
backend/auth.py - RBAC checks · Role-based authorization gatekeeping.
backend/rbac.py - Config · Environment-driven application settings.
backend/config.py - Hash helper · Local hashing helper used in security flows.
backend/generate_hash.py
RAG pipeline
Document ingestion and grounded question answering.
- RAG pipeline · Coordinates ingestion, retrieval, and answer generation.
backend/rag_pipeline.py - PDF parser · Extracts text from PDF inputs for ingestion.
backend/pdf_utils.py
Audit / logging
Operational logging and safety controls.
- Audit logger · Structured logging for sensitive actions.
backend/audit_logger.py - PII redactor · Redacts sensitive content before logging or reporting.
backend/pii_redactor.py - App logger · Shared logging configuration and output plumbing.
backend/logger.py
Local AI / storage
Runtime dependencies that stay local to the deployment.
- Ollama · Local model inference backend for grounded answers.
- Chroma · Persistent local semantic index for chunks and retrieval.
- Embeddings · Chunk embedding model used during ingestion.
Delivery / ops
Container, Kubernetes, and automation assets.
- Backend image · Container image for backend deployment.
Dockerfile.backend - K8s backend · Deployment, service, ingress, PVC, and secret templates.
deploy/k8s/backend/deployment.yaml - Monitoring stack · Grafana ingress and Prometheus stack values.
deploy/k8s/monitoring/kube-prometheus-stack-values.yaml - Deploy workflow · Automated backend deployment workflow.
.github/workflows/deploy-backend.yml
Connections 20
- 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.