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     │
│  Cloud SQL    │  │  Gemini 2.5   │  │  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 (Cloud SQL)
ORM	SQLAlchemy 2.0
Migrations	Alembic
AI	Vertex AI (Gemini 2.5 Flash)
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	Cloud SQL PostgreSQL
Cache	Memorystore for Redis
AI Services	Vertex AI (Gemini 2.5)
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

---