> For the complete documentation index, see [llms.txt](https://docs.mojai.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mojai.xyz/tehnicne-specifikacije/arhitektura.md).

# 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

{% stepper %}
{% step %}

### 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
  {% endstep %}

{% step %}

### 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)
  {% endstep %}
  {% endstepper %}

### 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:

```typescript
{
  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.

{% stepper %}
{% step %}

### 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`)
  {% endstep %}
  {% endstepper %}

#### 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):

{% stepper %}
{% step %}

### Check Cache

Preveri, ali obstaja aktiven `fileUri` v Gemini File API.
{% endstep %}

{% step %}

### JIT Upload

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

{% step %}

### Generate

Posreduje **Full Volume URI-je** v `gemini-2.5-flash` kontekstno okno.
{% endstep %}

{% step %}

### Result

Model prebere vsako stran izbranega volume-a za odgovor.
{% endstep %}
{% endstepper %}

### 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:

```typescript
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**

{% stepper %}
{% step %}

### 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)
  {% endstep %}

{% step %}

### 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
  {% endstep %}
  {% endstepper %}

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)

{% stepper %}
{% step %}

### 1. prepareDocumentContext()

* Smart Router izbere Admin/User PDF-je
* JIT Upload omogoči Long Context
  {% endstep %}

{% step %}

### 2. queryFrontierAgent() (Gemini 2.5 Flash)

* Input: User Query + RAG File Context (Tokens)
* Tools: Google Search Available
  {% endstep %}

{% step %}

### 3. Gemini Model Execution

* Prebere RAG Files (Deep Read)
* Izvede Google Search (če potrebno)
* Sintetizira odgovor s Citation Tokens \[1]
  {% endstep %}

{% step %}

### 4. Final Response

Final Response z 📚 RAG + 🌐 Internet sources\
Deduct 1.0 questions
{% endstep %}
{% endstepper %}

***

## 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

```javascript
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**

```bash
# Build optimiziran production bundle
npm run build

# Deploy na Firebase Hosting
firebase deploy --only hosting
```

**Backend**

```bash
# 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]