System Architecture of NISIRA Assistant

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HugoX2003/nisira-assistant/llms.txt

Use this file to discover all available pages before exploring further.

​

High-Level System Diagram

┌─────────────────────────────────────────────────────────────────┐
│  Browser                                                        │
│  React SPA  (/login · /register · /chat · /chat/:id            │
│              /admin · /admin/:tabId)                            │
└─────────────────────────┬───────────────────────────────────────┘
                          │  HTTPS  JWT Bearer token
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Django REST API  (backend/api/ + backend/core/)                │
│  • JWT auth          /api/auth/token/  /api/auth/refresh/       │
│  • Chat              /api/chat/                                 │
│  • Conversations     /api/conversations/                        │
│  • RAG control       /api/rag/*                                 │
│  • Admin panel       /api/admin/*                               │
│  • Ratings           /api/ratings/                             │
│  • Experiments       /api/experiments/                          │
│  • Documents         /api/documents/<slug>/                     │
└─────────────────────────┬───────────────────────────────────────┘
                          │  Python method call
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  RAG Pipeline  (backend/rag_system/)                            │
│                                                                 │
│  EmbeddingManager ──► VectorStore ◄── DriveManager             │
│  (all-mpnet-base-v2)  (Chroma/pgvector)  (Google Drive)        │
│                           │                                     │
│                     Hybrid Search                               │
│              (semantic 60% + lexical 40%)                       │
│                           │                                     │
│                       LLM Client                                │
│          (Gemini 2.0 Flash / OpenRouter / Groq)                 │
└─────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Databases                                                      │
│  MySQL / PostgreSQL  — conversations, messages, users,          │
│                        ratings, metrics, documents (binary)     │
│  ChromaDB / pgvector — 768-dim embeddings + chunk metadata      │
└─────────────────────────────────────────────────────────────────┘

​

Request Flow (Step by Step)

1. Authentication — The React frontend calls POST /api/auth/token/ with username and password. The server returns a short-lived JWT access token (24 hours) and a refresh token (7 days). Both are stored in localStorage and attached automatically as Authorization: Bearer <token> by the frontend/src/services/api.js interceptor.
2. Message submission — The user types a question and the frontend POSTs to /api/chat/ with { "content": "...", "conversation_id": "<slug or null>" }. If conversation_id is null, a new Conversation record (with a random URL-safe slug) is created.
3. Persistence — The Django view persists the incoming user message to the Message model and logs query metadata to QueryMetrics for later analysis.
4. Query reformulation — RAGPipeline.query() checks the recent conversation history. If the question is short, referential (“And how do you configure it?”), or contains demonstrative pronouns without a clear topic, the pipeline calls the LLM with a lightweight reformulation prompt to produce a self-contained search query before retrieval.
5. Embedding — EmbeddingManager encodes the (possibly reformulated) query into a 768-dimensional vector using sentence-transformers/all-mpnet-base-v2 running on CPU.
6. Hybrid search — The pipeline runs four complementary retrieval strategies concurrently and merges them:
   • Semantic search (weight 0.6): cosine similarity against all stored chunk embeddings.
   • Lexical search (weight 0.4): keyword frequency scoring, either via PostgreSQL full-text search (search_lexical) or a fallback ChromaDB scan.
   • Metadata search: filename and document-field keyword matching, with a high boost for exact source-name matches.
   • Expansion search: term-expansion fallback that kicks in when fewer than top_k results have been found.
7. Topic filtering — If the query contains recognized identifiers (ISO codes, law numbers, NTP standards, COBIT versions, etc.), chunks from unrelated documents are removed before the context is assembled.
8. Context assembly — The top-k chunks (3 for citation queries, 5 for general queries) are formatted as Fuente: <filename>\n<content> blocks and joined into a single context string.
9. LLM generation — The assembled context, conversation history, and original question are injected into the system prompt and sent to the configured LLM. When metrics collection is active, the pipeline uses streaming to capture time-to-first-token (TTFT) in milliseconds.
10. Response persistence — The bot’s answer and the source list (file_name, page, chunk_id, similarity_score, preview) are stored as a Message record with sources_json.
11. Frontend rendering — The React chat component renders the response as Markdown, displays source badges, and enables deep-linking to the exact page in the original document through an inline PDF viewer powered by the /api/documents/<slug>/ binary serving endpoint.

​

Backend Structure

​

api/ Models

​

RAG System Internals

​

Chunking Strategy

​

Dual Vector Store

VECTOR_STORE_BACKEND=postgres   →   PostgresVectorStore (production)
VECTOR_STORE_BACKEND=chroma     →   ChromaManager (local dev)
postgres + no DATABASE_URL      →   falls back to ChromaDB automatically

​

LLM Providers

​

Database Strategy

​

Authentication Flow

1. Login — POST /api/auth/login/ (custom view) or POST /api/auth/token/ (standard simplejwt view). Returns { "access": "...", "refresh": "..." }.
2. Token storage — The frontend stores both tokens in localStorage and reads the user payload from the access token to determine role.
3. Authenticated requests — Every protected API call includes Authorization: Bearer <access_token>. Django middleware validates the signature and expiry.
4. Token refresh — When the access token expires, the frontend calls POST /api/auth/refresh/ with the refresh token to receive a new access token.
5. Role-based routing — The React ProtectedRoute component reads localStorage for the token and checks whether user.username === 'admin'. Admin users can access /admin and /admin/:tabId; regular users are redirected to /chat.

​

Frontend Routing

​

Admin Panel API Endpoints