Architecture Overview

Technical architecture of the Vartovii platform.

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      FRONTEND                                │
│  React 19 + Vite + Tailwind + Framer Motion                 │
│  ├── Dashboard (company analysis)                           │
│  ├── Chat Widget (AI Agent)                                 │
│  └── Knowledge Base (Docusaurus)                            │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTPS
┌───────────────────────────▼─────────────────────────────────┐
│                    BACKEND API                               │
│  FastAPI + Python 3.13 + Uvicorn                            │
│  ├── /api/company/*    (Corporate endpoints)                │
│  ├── /api/ai/*         (AI Chat endpoints)                  │
│  ├── /api/agent/*      (Agent Tools endpoints)              │
│  ├── /api/scraping/*   (Scraping management)                │
│  ├── /api/v2/crypto/*  (Crypto module)                      │
│  └── /api/forensic/*   (Forensic Agent - on-chain)          │
└───────┬──────────────────┬──────────┬───────────────────────┘
        │                  │          │
┌───────▼───────┐  ┌───────▼───────┐  ┌───────▼───────┐
│  PostgreSQL   │  │  Vertex AI    │  │  External     │
│  (Neon)       │  │  Gemini 3.x   │  │  APIs         │
│  ├── reviews  │  │  ├── Chat     │  │  ├── Kununu   │
│  ├── companies│  │  ├── RAG      │  │  ├── Google   │
│  └── jobs     │  │  └── Function │  │  ├── Reddit   │
│               │  │      Calling  │  │  ├── CoinGecko│
│               │  │               │  │  └── DefiLlama│
└───────────────┘  └───────────────┘  └───────┬───────┘
                                              │
                                    ┌─────────▼─────────┐
                                    │  Google BigQuery  │
                                    │  Ethereum Dataset │
                                    │  (Forensic Agent) │
                                    └───────────────────┘

🛠️ Technology Stack

Backend

Component	Technology
Framework	FastAPI (Python 3.13)
Server	Uvicorn (ASGI)
Database	PostgreSQL 17 (Neon)
ORM	SQLAlchemy 2.0
Migrations	Alembic
AI	Vertex AI (Gemini 3 preview + 2.5 fallback)
Analytics	Google BigQuery (Ethereum dataset)

Frontend

Component	Technology
Framework	React 19
Build Tool	Vite
Styling	Tailwind CSS
State	TanStack Query
Charts	Nivo + Recharts
Animations	Framer Motion

Infrastructure

Component	Technology
Hosting	Google Cloud Run
Database	Neon PostgreSQL
Cache	Memorystore for Redis
AI Services	Vertex AI (Gemini 3 preview + 2.5 fallback)
Analytics	Google BigQuery (Ethereum)
Secrets	Secret Manager
Monitoring	Cloud Logging
CI/CD	Cloud Build + GitHub Actions

📁 Project Structure

Vartovii/
├── backend/
│   ├── main.py              # FastAPI app entry
│   ├── ai/                  # AI services
│   │   ├── config.py        # Model configuration
│   │   ├── client.py        # Gemini client
│   │   ├── prompts/         # System prompts
│   │   ├── services/        # Chat, sentiment, report
│   │   └── rag/             # RAG corpus management
│   ├── api/                 # API routers
│   ├── models/              # SQLAlchemy models
│   ├── services/            # Business logic
│   └── scrapers/            # Data collection
│
├── dashboard_app/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── pages/           # Route pages
│   │   ├── hooks/           # Custom hooks
│   │   └── api/             # API client
│   └── public/              # Static assets
│
├── knowledge-base/          # Docusaurus docs
│   ├── docs/                # Documentation files
│   └── docusaurus.config.js # Configuration
│
├── docs_site/               # Landing page
└── docs/                    # Internal docs (RAG indexed)

🔄 Data Flow

Company Analysis

1. User searches "BMW"
   └── Frontend → GET /api/search/smart?q=BMW

2. Smart Search checks freshness
   └── Backend → Database query
   └── If stale → Trigger scraping jobs

3. Return company data
   └── Backend → Frontend
   └── Display dashboard with Trust Score

AI Chat

1. User sends message
   └── Frontend → POST /api/ai/chat

2. Gemini analyzes intent
   └── Keywords detected? → Function Calling
   └── No keywords → Direct response

3. Tool execution (if needed)
   └── search_company, get_trust_score, etc.
   └── API calls to database

4. Response formatted
   └── Backend → Frontend
   └── Display in chat widget

Forensic Agent (On-Chain Analytics)

1. User asks "Check balance of 0xd8dA..."
   └── Frontend → POST /api/ai/chat
   └── AI detects wallet address keyword

2. Tool execution
   └── check_wallet function called
   └── BigQuery query to crypto_ethereum dataset
   └── CoinGecko API for USD price

3. Response with context
   └── ETH balance + USD value + Etherscan link
   └── Backend → Frontend → Display in chat

🔐 Security

• Authentication: API key for agent endpoints
• Authorization: IAM-based access control
• Encryption: HTTPS everywhere, at-rest encryption
• Secrets: Google Secret Manager

📊 Performance

Metric	Target	Actual
API Response (cached)	under 100ms	~50ms
API Response (DB)	under 500ms	~200ms
Chat Response	under 3s	~1.5s
Page Load	under 2s	~1.2s

---