Arhitektura

Pregled Sistema

Moj AI je napredni AI pravni pomočnik, specializiran za slovensko gradbeno zakonodajo in prostorsko načrtovanje. Aplikacija deluje kot profesionalno orodje za navigacijo po kompleksni slovenski zakonodaji s področja gradbeništva, vključno z GZ (Gradbeni Zakon), ZUreP-3 (Zakon o urejanju prostora) in občinskimi prostorskimi načrti (OPN).

Status: Production Ready Zadnja posodobitev: Januar 2026 Arhitektura: Multi-tenant, Cloud-Native

---

Tehnološki Stack (Technology Stack)

Frontend Layer

Framework & Build Tools

• React 19.2.3 s TypeScript za type-safe razvoj

• Vite 6.2.0 za hiter development in optimizirane production build-e

• Tailwind CSS za responsive in konsistenten UI design

State Management

• React Context API za centralizirano upravljanje stanja:

  • AuthContext - avtentikacija in uporabniški profil

  • LanguageContext - večjezičnost (slovenščina/angleščina)

  • ThemeContext - svetla/temna tema

Deployment

• Firebase Hosting z CDN distribucijo

• Avtomatično SSL/TLS šifriranje

• Cache-Control optimizacija za aplikacijske resurse

Backend Layer

Runtime Environment

• Firebase Cloud Functions (Node.js 20)

• Generation 2 (V2) funkcije za izboljšano performance

• Timeouts: 300 sekund za kompleksne AI operacije

• Memory: 1GiB RAM za zahtevne procesne operacije

1

Core Functions

Opis osnovnih Cloud Functions, ki poganjajo backend.

• health() - Health check endpoint

• askGemini() - Glavna AI orchestration funkcija

• uploadFile() - Upravljanje z dokumenti (Direct V2 handler)

• deleteDocumentFromFileSearch() - Brisanje dokumentov iz knjižnice

• queryFileSearch() - Direktne poizvedbe po dokumentih

• handleStripeWebhook() - Procesiranje plačil

2

Agent Orchestration Functions (Frontier Mode)

Funkcije za orkestracijo agentov v Frontier načinu.

• queryRAGAgent() - Specialist za dokumente (Smart Router + Long Context)

• queryFrontierAgent() - Unified Research Agent (RAG + Google Search)

• orchestrateAgents() - Glavni koordinator (router med RAG in Frontier)

AI Layer (Gemini)

Modeli

• Lightning Mode: gemini-2.5-flash s File Search

• Frontier Mode: gemini-2.5-flash z Agent Orchestration

• RAG Operations: Direct File API (Multimodal)

Google Gemini API Integration

• SDK: @google/genai v0.1.0+

• Streaming responses za real-time interakcijo

• Token-based citation system

• Multimodal capabilities (tekst + PDF)

Database Layer

Firestore (Native Mode)

Struktura podatkovnih zbirk:

├── users/{uid}
│   ├── Uporabniški profil
│   ├── Naročniške informacije
│   ├── Statistika uporabe
│   └── conversations/{convId}
│       └── Zgodovina pogovorov
├── fileSearchStores/{storeId}
│   └── Metadata index za RAG sistem
├── documents/{docId}
│   └── Sledenje naloženim dokumentom
└── systemPrompts
    └── AI system prompts (admin)

Značilnosti

• Real-time sinhronizacija

• Offline podpora

• Avtomatsko indeksiranje

• Atomične transakcije

• Strong consistency model

Storage Layer

Cloud Storage

Organizacija bucket-ov:

├── user-documents/
│   └── {userId}/
│       ├── Uporabniški PDF-ji
│       └── Naloženi dokumenti
└── admin-documents/
    ├── Zakonodaja (ZGO, ZUreP-3)
    └── OPN-ji

Varnostne Značilnosti

• Šifriranje at-rest

• Avtomatski backup

• Multi-region replikacija

• Verzioniranje dokumentov

Payment Integration

Stripe

• Per-question billing model

• Podpora za slovensko DDV

• Webhook signature verification

• Avtomatično generiranje računov

• Zbiranje podatkov o podjetju

Pricing

• Lightning Mode: 0.5 vprašanja

• Frontier Mode: 1.0 vprašanje

---

RAG Sistem - Hybrid Smart Router

Arhitekturni Pristop: "Route-then-Read"

Moj AI uporablja napredni Hybrid Smart Router sistem namesto tradicionalnih vector store rešitev. Ta pristop združuje deterministično Firestore metadata knjižnico z Gemini-jevim obsežnim Long Context oknom za natančno branje celotnih dokumentov.

Komponente RAG Sistema

1. The Library (Storage Layer)

Master Copy: Dokumenti so shranjeni v Firebase Storage

• Lokacija: gs://user-documents/...

• Arhivska kopija vseh PDF datotek

Metadata Index: Firestore collection fileSearchStores Fungira kot "kataložni sistem" z naslednjimi atributi:

{
  filename: "OPN_Ziri.pdf",
  keywords: ["Žiri", "Construction", "OPN"],
  city: "Žiri",
  type: "OPN" | "Law" | "User",
  uploadDate: Timestamp,
  fileSize: number
}

2. Smart Router (Selection Layer)

Ko uporabnik postavi vprašanje, lahek Router Agent (gemini-2.0-flash-exp) analizira poizvedbo glede na Metadata Index.

1

Proces Smart Router-a

• Input: "Kaj ustreza 58. členu v Žireh?"

• Scan: Router pregleda documentLibrary

• Select: Identificira OPN_Ziri.pdf kot najbolj relevanten vir

• Comparison: Pri primerjavi izbere več dokumentov (npr. "Primerjaj Žiri in Ljubljana" → OPN_Ziri.pdf + OPN_Ljubljana.pdf)

3. Automated Partitioning (Split Strategy)

Za dokumente, ki presegajo 1 milijon tokenov (približno 300 strani), sistem avtomatsko izvede particijo med nalaganjem.

Primer:

Original: Large_OPN.pdf (500 strani)

Volumes:
├── Large_OPN_Vol1.pdf (strani 1-250)
└── Large_OPN_Vol2.pdf (strani 251-500)

Routing: Smart Router izbere specifične volume glede na vsebino
poizvedbe (npr. "Pravila za cono X" → izbere Vol 2)

Prednosti:

• Omogoča uporabo ekonomičnega gemini-2.5-flash modela

• Optimizira stroške brez izgube natančnosti

• Ohranja celovitost kompleksnih tabel

4. Deep Read (Generation Layer)

Ko so dokumenti (ali volume-i) izbrani (max 3):

1

Check Cache

Preveri, ali obstaja aktiven fileUri v Gemini File API.

2

JIT Upload

Če fileUri ne obstaja (ali je potekel >48h), stream iz Firebase Storage → Gemini File API.

3

Generate

Posreduje Full Volume URI-je v gemini-2.5-flash kontekstno okno.

4

Result

Model prebere vsako stran izbranega volume-a za odgovor.

Prednosti Hybrid RAG Sistema

• Cost Efficiency: Eliminira potrebo po dragih Pro modelih

• Table Accuracy: Native PDF branje ohranja kompleksne tabelne strukture

• Scale: Knjižnica lahko vsebuje 1000+ PDF-jev, naložimo samo relevantne

• Deterministic: Brez "black-box" vector store-ov, popoln nadzor nad izbiro dokumentov

• Fresh Data: JIT upload strategija zagotavlja aktualne dokumente

---

Orchestration Modes - Dual-Mode Arhitektura

Moj AI ponuja dva inteligentno optimizirana načina delovanja:

Lightning Mode ⚡

Namen: Hitri, dokumentno usmerjeni odgovori za pravne poizvedbe

Capabilities:

• Dostop do Admin File Search Store (zakonodaja, OPN-ji)

• Dostop do User File Search Store (uporabniški dokumenti)

• Brez internetnega iskanja (offline-capable)

• Optimizirano za: Preverjanje specifičnih predpisov, hitre pojasnitve

Tehnična Implementacija:

const model = 'gemini-2.5-flash';
const tools = []; // Brez internetnega dostopa
const stores = ['admin-file-search-store', `user-${userId}-file-search-store`];

Performance: 5-15 sekund Cena: 0.5 vprašanja

System Prompt: Slovensko usmerjen AI pravni pomočnik s poudarkom na:

• Zakonodaja (ZGO, ZUreP-3)

• Občinski prostorski načrti (OPN)

• Source attribution: 📚 RAG + 🧠 General knowledge

Frontier Mode 🔍

Namen: Celoviti, raziskovalno podprti odgovori, ki združujejo RAG, internet in splošno znanje

Capabilities:

• Dostop do Admin + User dokumentov (RAG)

• Google Search Tool za trenutne informacije

• Združuje več virov sočasno

• Optimizirano za: Tržne raziskave, gradbeni stroški, nepremičninski trendi

Agent Orchestration Architecture:

User Query
    ↓
1. prepareDocumentContext() - Smart Router skenira knjižnico, izbere PDF-je, JIT Upload v Gemini, ustvari Source Map
    ↓
2. queryFrontierAgent() - System Prompt (z Source Map), Tools: [Google Search], Context: [RAG File Parts]
    ↓
Response z 📚 RAG + 🌐 Internet Attribution

Unified Frontier Components

1

prepareDocumentContext()

• Uporabi Smart Router za iskanje dokumentov v Admin/User knjižnici

• JIT Upload izbranih dokumentov v Gemini

• Vrne parts (file data) in sources (metadata)

2

queryFrontierAgent()

• Injicira RAG parts v kontekstno okno

• Omogoči googleSearch tool

• Injicira Source Map v system prompt:

  Source [1]: OPN_Ziri.pdf (Type: RAG)
  Source [2]: ZGO_Official.pdf (Type: RAG)

• Navodila: "Citiraj z uporabo [ID] za RAG vire, standardno tool citation za Web"

• Vrne končni odgovor z veljavnim markdown formatiranjem

Performance: 15-30 sekund Cena: 1.0 vprašanje

System Prompt: Slovensko usmerjen AI raziskovalni asistent s poudarkom na:

• Pravna podlaga (dokumenti)

• Trenutne tržne razmere (internet)

• Strokovne ocene (general knowledge)

• Source attribution: 📚 RAG + 🌐 Internet + 🧠 General knowledge

Primerjalna Tabela

Značilnost	Lightning	Frontier
Model	gemini-2.5-flash	gemini-2.5-flash (Orchestrated)
RAG Dostop	✅ Admin + user docs	✅ Admin + user docs
Internet	❌ Ne	✅ Google Search
Hitrost	⚡ 5-15 sekund	🔍 15-30 sekund
Cena	0.5 vpr.	1.0 vpr.
Use Case	Hitri pravni odgovori	Raziskovalne analize

---

Data Flow Architecture

Celotni Podatkovni Tok

User Login (Google OAuth)
    ↓
Firebase Auth
    ↓
Load User Profile & Conversations (Firestore)
    ↓
Display Dashboard
    ↓
[Opcijsko] File Upload 
    ↓
Cloud Function: uploadFile() (Direct V2)
    ├─ Buffer Stream (Busboy)
    ├─ Validate (Size/Type)
    ├─ Cloud Storage (Archival)
    ├─ Gemini File API (Multimodal URI)
    └─ Firestore Metadata
    ↓
User Query + Attachments [URI]
    ↓
Cloud Function: askGemini()
    ├─ Orchestrate Agents
    │   ├─ Lightning: RAG Agent (Smart Router + Long Context) → Response
    │   └─ Frontier: Frontier Agent (RAG Context + Google Search Tool) → Response
    ├─ Post-Processing: Tokens [1] → Links (če potrebno)
    ├─ Inject Attachments (Multimodal)
    └─ Save conversation (Firestore)
    ↓
Stream Response to UI
    ↓
Save to Firestore

Lightning Mode Data Flow

User Query
    ↓
Load Admin + User RAG Stores
    ↓
Use File Search Tool
    ↓
Query RAG Documents
    ↓
Response z 📚 RAG sources
    ↓
Deduct 0.5 questions

Frontier Mode Data Flow (Unified Execution)

1

1. prepareDocumentContext()

• Smart Router izbere Admin/User PDF-je

• JIT Upload omogoči Long Context

2

2. queryFrontierAgent() (Gemini 2.5 Flash)

• Input: User Query + RAG File Context (Tokens)

• Tools: Google Search Available

3

3. Gemini Model Execution

• Prebere RAG Files (Deep Read)

• Izvede Google Search (če potrebno)

• Sintetizira odgovor s Citation Tokens [1]

4

4. Final Response

Final Response z 📚 RAG + 🌐 Internet sources Deduct 1.0 questions

---

Varnost in Zasebnost

Authentication Model

Google OAuth 2.0

• Firebase Auth z Google identity provider

• Varni JWT tokeni

• Avtomatski token refresh

• Session management

Authorization

• Role-based access control (user/admin)

• Per-user data isolation

• Firestore security rules

Data Protection

Šifriranje

• Encryption at rest (Firebase Storage)

• Encryption in transit (TLS/SSL)

• Secure API key management (Cloud Functions environment)

Privacy

• Per-user File Search Stores (izolacija dokumentov)

• Admin documents - dostopni vsem uporabnikom

• User documents - dostopni samo lastniku

• Brez deljenja podatkov med uporabniki

Stripe Integration

• Webhook signature verification

• Secure payment processing

• PCI-DSS compliance preko Stripe

• Slovensko DDV procesiranje

Firestore Security Rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User documents
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
      
      // Conversations
      match /conversations/{conversationId} {
        allow read, write: if request.auth.uid == userId;
      }
    }
    
    // Admin only
    match /systemPrompts/{promptId} {
      allow read: if request.auth != null;
      allow write: if request.auth.token.admin == true;
    }
  }
}

---

Deployment Architecture

Production Environment

Diagram prikazuje komponente: Client Layer (Browser/Mobile/Tablet) → Firebase Hosting → Firebase Auth → Cloud Functions V2 → Firestore / Storage / Gemini API → Stripe.

Deployment Process

Frontend

# Build optimiziran production bundle
npm run build

# Deploy na Firebase Hosting
firebase deploy --only hosting

Backend

# Deploy Cloud Functions
firebase deploy --only functions

# Deploy Firestore rules
firebase deploy --only firestore:rules

Environment Variables

• Ločeno upravljanje development/production

• Varne ključe shranjujemo v Cloud Functions environment

• Brez hardcoded secrets v kodi

---

Performance Optimizations

Frontend Optimizations

• Code Splitting: React.lazy() za route-based splitting

• Dynamic imports za velike komponente

• Service Workers za offline capability

• IndexedDB za lokalno shranjevanje pogovorov

• Optimistic UI updates

• Vite production build optimizacije, tree-shaking, minification

Backend Optimizations

• Cloud Functions Generation 2 (V2)

• 1GiB memory allocation za AI operacije

• 300s timeout za kompleksne procese

• Concurrent execution za Frontier mode

• Firestore: composite indexes, pagination, real-time listeners samo kjer potrebno

• RAG System: JIT upload, 48-urni cache Gemini File API, Smart Router za minimizacijo prenESov

---

Monitoring in Logging

Firebase Monitoring

• Page load times

• API response times

• Error rates

Cloud Functions Logs

• Structured logging

• Error tracking

• Performance metrics

Firestore Usage

• Read/write operations

• Storage usage

• Index performance

Cost Monitoring

• Gemini API Usage: Token consumption tracking, model usage statistics, cost per query analytics

• Cloud Functions: Invocation counts, execution time, memory usage

• Storage: File storage costs, network egress, backup costs

---

Scalability

Horizontal Scaling

• Cloud Functions: avtomatično skaliranje, concurrent execution do 1000 instances, per-function configuration

• Firestore: automatic sharding, multi-region replication, unlimited scaling capability

Vertical Scaling

• Memory Allocation: 1GiB za AI-intensive funkcije, 256MiB za lahke operacije

• Timeout Configuration: 300s za kompleksne AI operacije, 60s za standardne operacije

---

Tehnološke Inovacije

1. Hybrid Smart Router RAG System

   • Deterministična metadata knjižnica + Long Context okno za natančno branje dokumentov

2. Agent-as-a-Tool Orchestration

   • Unified Frontier Agent, simultano procesiranje RAG in Web virov, source mapping s [ID] tokens

3. Automated Document Partitioning

   • Particioniranje velikih dokumentov (>300 strani) v volume-e

4. JIT Upload Strategy

   • Nalaganje samo aktivno potrebnih dokumentov, 48-urni cache window

5. Multi-Source Attribution System

   • Transparenten sistem citiranja z emoji indikatorji:

     • 📚 RAG sources (File Search)

     • 🌐 Internet sources (Google Search)

     • 🧠 General knowledge (AI reasoning)

---

Zaključek

Moj AI predstavlja sofisticirano cloud-native rešitev za slovenski gradbeni sektor, ki združuje:

• Napredne AI capabilities (Gemini 2.5)

• Hybrid RAG arhitekturo

• Agent orchestration pattern

• Multi-tenant infrastructure

• Enterprise-grade security

Sistem je zasnovan za visoko zanesljivost, skalabilnost in cost-efficiency, hkrati pa ohranja transparentnost virov in natančnost pravnih informacij.

---

Verzija dokumenta: 1.0 Datum: Januar 2026 Kontakt: [Vaša kontaktna informacija za public docs]