# dangshark/ai-guardian architecture

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

- Interactive diagram: https://gitdiagram.com/dangshark/ai-guardian
- Repository: https://github.com/dangshark/ai-guardian

## Overview

1. **System shape**
   - This is a two-app stack: a **Next.js frontend** and a **FastAPI backend**, deployed together with Docker Compose.
   - The backend depends on external infrastructure for **PostgreSQL**, **MinIO** object storage, **Weaviate** vector search, and LLM providers such as **Azure OpenAI** and optionally **Gemini**.

2. **Frontend boundary**
   - The frontend is a Next.js App Router app with distinct surfaces for **landing**, **login/signup**, **OAuth callback**, **chat sessions**, and **file management**.
   - It is mostly a presentation and orchestration layer: it fetches data from the backend, manages session/auth state, and renders chat/file UX through reusable components.

3. **Frontend auth/session handling**
   - Authentication is mediated through a Supabase client/middleware setup in `src/utils/supabase`, plus a frontend `AuthContext`.
   - The callback route and middleware suggest browser-session handling and protected routes on the client side, while actual user records still live in the backend database.

4. **Backend API layer**
   - The FastAPI app is organized by domain routers: **user**, **chat**, **file**, **mask**, and **ai**.
   - `app/main.py` is the entrypoint, `dependencies.py` centralizes shared dependencies, and `config.py` holds environment-driven configuration.

5. **Backend domain model**
   - The persistence layer is built around SQLAlchemy models for **users**, **profiles**, **chat sessions**, **messages**, **files**, **message-file links**, **PII/mask mappings**, and **RAG documents**.
   - Alembic migrations indicate the database schema is a first-class part of the system and likely the source of truth for user/chat/file metadata.

6. **Chat orchestration**
   - `chat_service.py` is the main conversational coordinator, with chat sessions and messages persisted in the database.
   - The chat flow is likely: frontend sends a message → backend stores it → the service decides whether to answer directly or route to RAG/other agents → response is streamed or returned and saved.

7. **PII detection and masking pipeline**
   - `extraction_service.py`, `masking_service.py`, and `unmasking_service.py` form the privacy layer around user content.
   - The app uses PII-related models and routes to detect sensitive entities, replace them with masks during processing, and later restore them when safe to do so; this is a core cross-cutting concern in both chat and file flows.

8. **File ingestion and storage**
   - File upload is handled through the backend file API and stored in **MinIO**, with metadata tracked in the database.
   - Uploaded files are also extracted into text via the extraction service, enabling downstream chat attachment handling and RAG ingestion.

9. **RAG subsystem**
   - RAG is a separate backend subsystem centered on `services/RAG_service.py` and `services/agents/rag_agent`.
   - The agent stack includes **query expansion**, **reranking**, **response generation**, and a **Weaviate vector store adapter**, which together support document-based Q&A over ingested content.

10. **Agent routing and model integration**
   - `services/agents/agent_decision.py` indicates a decision layer that chooses between conversational and retrieval-backed behavior.
   - The system is configured for multiple LLM tasks with different model settings, so the architecture treats “decision,” “chat response,” and “RAG response” as separate inference paths rather than one monolithic prompt.

11. **Data flow across stores**
   - The important runtime path is: **frontend → FastAPI routers → services → PostgreSQL / MinIO / Weaviate / LLM APIs**.
   - PostgreSQL stores durable app state, MinIO stores file blobs, Weaviate stores embeddings and similarity-searchable chunks, and LLM providers generate masked or retrieval-augmented responses.

12. **Operational and validation tooling**
   - `docker-compose.yml`, backend/frontend Dockerfiles, and environment templates define the deployable boundary.
   - The backend also includes `tests/` plus a substantial `benchmarks/` folder for PII evaluation, suggesting the privacy extraction layer is actively measured and tuned as part of the system architecture.

Main entry points: [`backend/app/api/routers`](https://github.com/dangshark/ai-guardian/tree/main/backend/app/api/routers) (API routers), [`frontend/src/app`](https://github.com/dangshark/ai-guardian/tree/main/frontend/src/app) (Next.js app), [`backend/app/services/minio_service.py`](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/minio_service.py) (File service), [`backend/app/services/RAG_service.py`](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/RAG_service.py) (RAG stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js app<br/>ui shell"]
  node_frontend_auth["Auth state<br/>session layer"]
  node_frontend_chat_ui["Chat UI<br/>interaction layer"]
  node_frontend_files["File manager<br/>file UX<br/>[file-manager.tsx]"]
  node_frontend_api["API clients<br/>data access<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>api entrypoint<br/>[main.py]"]
  node_backend_config["Config<br/>settings<br/>[config.py]"]
  node_backend_routers["API routers<br/>domain API"]
  node_backend_chat["Chat service<br/>conversation orchestration<br/>[chat_service.py]"]
  node_backend_privacy["PII pipeline<br/>privacy processing<br/>[masking_service.py]"]
  node_backend_file["File service<br/>ingestion/storage<br/>[minio_service.py]"]
  node_backend_rag["RAG stack<br/>retrieval subsystem<br/>[RAG_service.py]"]
  node_backend_agent["Agent routing<br/>model decision<br/>[agent_decision.py]"]
  node_backend_models["Domain models<br/>persistence model"]
  node_backend_migrations["Migrations<br/>schema evolution"]
end

subgraph group_infra["Infra"]
  node_infra_pg[("PostgreSQL<br/>relational store")]
  node_infra_minio[("MinIO<br/>object storage")]
  node_infra_weaviate[("Weaviate<br/>vector store")]
  node_infra_llm(("LLM APIs<br/>model providers"))
end

subgraph group_ops["Ops"]
  node_ops_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
end

node_ops_compose -->|"runs"| node_frontend_app
node_ops_compose -->|"runs"| node_backend_main
node_frontend_app -->|"auth"| node_frontend_auth
node_frontend_app -->|"renders"| node_frontend_chat_ui
node_frontend_app -->|"renders"| node_frontend_files
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_auth -->|"authorizes"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_routers
node_backend_main -->|"loads"| node_backend_config
node_backend_main -->|"mounts"| node_backend_routers
node_backend_routers -->|"delegates"| node_backend_chat
node_backend_routers -->|"delegates"| node_backend_privacy
node_backend_routers -->|"delegates"| node_backend_file
node_backend_routers -->|"delegates"| node_backend_rag
node_backend_chat -->|"chooses path"| node_backend_agent
node_backend_agent -->|"routes to"| node_backend_rag
node_backend_chat -->|"persists"| node_backend_models
node_backend_file -->|"extracts text"| node_backend_privacy
node_backend_file -->|"stores metadata"| node_backend_models
node_backend_privacy -->|"maps pii"| node_backend_models
node_backend_rag -->|"queries"| node_infra_weaviate
node_backend_rag -->|"generates"| node_infra_llm
node_backend_file -->|"stores blobs"| node_infra_minio
node_backend_models -->|"persists"| node_infra_pg
node_backend_migrations -->|"evolves schema"| node_infra_pg

click node_frontend_app "https://github.com/dangshark/ai-guardian/tree/main/frontend/src/app"
click node_frontend_auth "https://github.com/dangshark/ai-guardian/tree/main/frontend/src/utils/supabase"
click node_frontend_chat_ui "https://github.com/dangshark/ai-guardian/tree/main/frontend/src/components/chat"
click node_frontend_files "https://github.com/dangshark/ai-guardian/blob/main/frontend/src/components/file-manager.tsx"
click node_frontend_api "https://github.com/dangshark/ai-guardian/blob/main/frontend/src/utils/api.ts"
click node_backend_main "https://github.com/dangshark/ai-guardian/blob/main/backend/app/main.py"
click node_backend_config "https://github.com/dangshark/ai-guardian/blob/main/backend/app/config.py"
click node_backend_routers "https://github.com/dangshark/ai-guardian/tree/main/backend/app/api/routers"
click node_backend_chat "https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/chat_service.py"
click node_backend_privacy "https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/masking_service.py"
click node_backend_file "https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/minio_service.py"
click node_backend_rag "https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/RAG_service.py"
click node_backend_agent "https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/agents/agent_decision.py"
click node_backend_models "https://github.com/dangshark/ai-guardian/tree/main/backend/app/models"
click node_backend_migrations "https://github.com/dangshark/ai-guardian/tree/main/backend/alembic"
click node_ops_compose "https://github.com/dangshark/ai-guardian/blob/main/docker-compose.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_frontend_app,node_frontend_auth,node_frontend_chat_ui,node_frontend_files,node_frontend_api toneBlue
class node_backend_main,node_backend_config,node_backend_routers,node_backend_chat,node_backend_privacy,node_backend_file,node_backend_rag,node_backend_agent,node_backend_models,node_backend_migrations toneAmber
class node_infra_pg,node_infra_minio,node_infra_weaviate,node_infra_llm toneMint
class node_ops_compose toneRose
```

## Components

### Frontend

Next.js App Router UI and client-side orchestration

- [Next.js app](https://github.com/dangshark/ai-guardian/tree/main/frontend/src/app): ui shell · App Router surfaces for landing, auth, chat, and file management · `frontend/src/app`
- [Auth state](https://github.com/dangshark/ai-guardian/tree/main/frontend/src/utils/supabase): session layer · Supabase client, middleware, and browser auth context · `frontend/src/utils/supabase`
- [Chat UI](https://github.com/dangshark/ai-guardian/tree/main/frontend/src/components/chat): interaction layer · Chat session page and reusable message/input/session components · `frontend/src/components/chat`
- [File manager](https://github.com/dangshark/ai-guardian/blob/main/frontend/src/components/file-manager.tsx): file UX · File browsing and upload-oriented frontend surfaces · `frontend/src/components/file-manager.tsx`
- [API clients](https://github.com/dangshark/ai-guardian/blob/main/frontend/src/utils/api.ts): data access · Frontend request helpers and service wrappers for backend calls · `frontend/src/utils/api.ts`

### Backend

FastAPI API, services, and persistence models

- [FastAPI app](https://github.com/dangshark/ai-guardian/blob/main/backend/app/main.py): api entrypoint · Backend application bootstrap and router assembly · `backend/app/main.py`
- [Config](https://github.com/dangshark/ai-guardian/blob/main/backend/app/config.py): settings · Environment-driven backend configuration and shared dependencies · `backend/app/config.py`
- [API routers](https://github.com/dangshark/ai-guardian/tree/main/backend/app/api/routers): domain API · User, chat, file, mask, and AI route boundaries · `backend/app/api/routers`
- [Chat service](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/chat_service.py): conversation orchestration · Coordinates session state, message persistence, and response flow · `backend/app/services/chat_service.py`
- [PII pipeline](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/masking_service.py): privacy processing · Extraction, masking, and unmasking for sensitive content · `backend/app/services/masking_service.py`
- [File service](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/minio_service.py): ingestion/storage · Upload handling, object storage integration, and file metadata flow · `backend/app/services/minio_service.py`
- [RAG stack](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/RAG_service.py): retrieval subsystem · Retrieval-augmented generation orchestration and agent components · `backend/app/services/RAG_service.py`
- [Agent routing](https://github.com/dangshark/ai-guardian/blob/main/backend/app/services/agents/agent_decision.py): model decision · Chooses between direct chat and retrieval-backed inference paths · `backend/app/services/agents/agent_decision.py`
- [Domain models](https://github.com/dangshark/ai-guardian/tree/main/backend/app/models): persistence model · Users, profiles, chats, messages, files, masks, and RAG documents · `backend/app/models`
- [Migrations](https://github.com/dangshark/ai-guardian/tree/main/backend/alembic): schema evolution · Alembic database migration history · `backend/alembic`

### Infra

External data stores and model providers

- **PostgreSQL**: relational store · Durable application state and metadata store
- **MinIO**: object storage · Blob storage for uploaded files and extracted artifacts
- **Weaviate**: vector store · Embedding and similarity search backend for RAG
- **LLM APIs**: model providers · Azure OpenAI and optional Gemini inference providers

### Ops

Container and migration boundary

- [Compose](https://github.com/dangshark/ai-guardian/blob/main/docker-compose.yml): deployment · Docker Compose deployment boundary for the two-app stack · `docker-compose.yml`

## Connections

- Compose → Next.js app: runs · Containerizes the frontend app
- Compose → FastAPI app: runs · Containerizes the backend app
- Next.js app → Auth state: auth · Routes and components rely on browser session state
- Next.js app → Chat UI: renders · Chat page composes reusable chat components
- Next.js app → File manager: renders · File surface provides upload and browse UX
- Next.js app → API clients: calls · UI talks to backend through shared request helpers
- Auth state → API clients: authorizes · Supabase-backed session context attaches auth to requests
- API clients → API routers: requests · Frontend invokes domain API routes
- FastAPI app → Config: loads · Bootstraps configuration and dependencies from environment
- FastAPI app → API routers: mounts · Registers domain routers into the FastAPI app
- API routers → Chat service: delegates · Chat endpoints route into orchestration service
- API routers → PII pipeline: delegates · Mask and PII endpoints use privacy processing
- API routers → File service: delegates · File endpoints use ingestion and storage service
- API routers → RAG stack: delegates · AI and retrieval endpoints route into RAG subsystem
- Chat service → Agent routing: chooses path · Conversation flow branches into direct or retrieval-backed responses
- Agent routing → RAG stack: routes to · Retrieval path invokes the RAG stack
- Chat service → Domain models: persists · Sessions and messages are stored in domain models
- File service → PII pipeline: extracts text · Uploaded files are processed for sensitive content and downstream use
- File service → Domain models: stores metadata · Files and attachments are tracked in database models
- PII pipeline → Domain models: maps pii · PII and mask mappings are recorded in persistence
- RAG stack → Weaviate: queries · Vector search over embedded chunks
- RAG stack → LLM APIs: generates · LLM providers produce retrieval-augmented responses
- File service → MinIO: stores blobs · Uploaded file contents live in object storage
- Domain models → PostgreSQL: persists · Primary relational state is stored in PostgreSQL
- Migrations → PostgreSQL: evolves schema · Alembic manages the database schema used by the models
