How dangshark/ai-guardian works
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: routers API routers · app Next.js app · minio_service.py File service · RAG_service.py RAG stack
Components 20
Frontend
Next.js App Router UI and client-side orchestration
- Next.js app · App Router surfaces for landing, auth, chat, and file management
frontend/src/app - Auth state · Supabase client, middleware, and browser auth context
frontend/src/utils/supabase - Chat UI · Chat session page and reusable message/input/session components
frontend/src/components/chat - File manager · File browsing and upload-oriented frontend surfaces
frontend/src/components/file-manager.tsx - API clients · Frontend request helpers and service wrappers for backend calls
frontend/src/utils/api.ts
Backend
FastAPI API, services, and persistence models
- FastAPI app · Backend application bootstrap and router assembly
backend/app/main.py - Config · Environment-driven backend configuration and shared dependencies
backend/app/config.py - API routers · User, chat, file, mask, and AI route boundaries
backend/app/api/routers - Chat service · Coordinates session state, message persistence, and response flow
backend/app/services/chat_service.py - PII pipeline · Extraction, masking, and unmasking for sensitive content
backend/app/services/masking_service.py - File service · Upload handling, object storage integration, and file metadata flow
backend/app/services/minio_service.py - RAG stack · Retrieval-augmented generation orchestration and agent components
backend/app/services/RAG_service.py - Agent routing · Chooses between direct chat and retrieval-backed inference paths
backend/app/services/agents/agent_decision.py - Domain models · Users, profiles, chats, messages, files, masks, and RAG documents
backend/app/models - Migrations · Alembic database migration history
backend/alembic
Infra
External data stores and model providers
- PostgreSQL · Durable application state and metadata store
- MinIO · Blob storage for uploaded files and extracted artifacts
- Weaviate · Embedding and similarity search backend for RAG
- LLM APIs · Azure OpenAI and optional Gemini inference providers
Ops
Container and migration boundary
- Compose · Docker Compose deployment boundary for the two-app stack
docker-compose.yml
Connections 25
- 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