Architekturübersicht

Technische Architektur der Vartovii-Plattform.

🏗️ Systemarchitektur

┌─────────────────────────────────────────────────────────────┐
│                      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) │
                                    └───────────────────┘

🛠️ Technologie-Stack

Backend

Komponente	Technologie
Framework	FastAPI (Python 3.13)
Server	Uvicorn (ASGI)
Datenbank	PostgreSQL 17 (Cloud SQL)
ORM	SQLAlchemy 2.0
Migrationen	Alembic
KI	Vertex AI (Gemini 2.5 Flash)
Analysen	Google BigQuery (Ethereum dataset)

Frontend

Komponente	Technologie
Framework	React 19
Build-Tool	Vite
Styling	Tailwind CSS
State	TanStack Query
Diagramme	Nivo + Recharts
Animationen	Framer Motion

Infrastruktur

Komponente	Technologie
Hosting	Google Cloud Run
Datenbank	Cloud SQL PostgreSQL
Cache	Memorystore for Redis
KI-Dienste	Vertex AI (Gemini 2.5)
Analysen	Google BigQuery (Ethereum)
Secrets	Secret Manager
Monitoring	Cloud Logging
CI/CD	Cloud Build + GitHub Actions

📁 Projektstruktur

Vartovii/
├── backend/
│   ├── main.py              # FastAPI-App-Einstiegspunkt
│   ├── ai/                  # KI-Dienste
│   │   ├── config.py        # Modellkonfiguration
│   │   ├── client.py        # Gemini-Client
│   │   ├── prompts/         # System-Prompts
│   │   ├── services/        # Chat, Sentiment, Bericht
│   │   └── rag/             # RAG-Korpusverwaltung
│   ├── api/                 # API-Router
│   ├── models/              # SQLAlchemy-Modelle
│   ├── services/            # Geschäftslogik
│   └── scrapers/            # Datenerfassung
│
├── dashboard_app/
│   ├── src/
│   │   ├── components/      # React-Komponenten
│   │   ├── pages/           # Routen-Seiten
│   │   ├── hooks/           # Benutzerdefinierte Hooks
│   │   └── api/             # API-Client
│   └── public/              # Statische Assets
│
├── knowledge-base/          # Docusaurus-Dokumentation
│   ├── docs/                # Dokumentationsdateien
│   └── docusaurus.config.js # Konfiguration
│
├── docs_site/               # Landing Page
└── docs/                    # Interne Dokumentation (RAG-indiziert)

🔄 Datenfluss

Unternehmensanalyse

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

2. Smart Search prüft Aktualität
   └── Backend → Datenbankabfrage
   └── Wenn veraltet → Scraping-Jobs auslösen

3. Unternehmensdaten zurückgeben
   └── Backend → Frontend
   └── Dashboard mit Trust Score anzeigen

AI Chat

1. Benutzer sendet Nachricht
   └── Frontend → POST /api/ai/chat

2. Gemini analysiert Absicht
   └── Keywords erkannt? → Function Calling
   └── Keine Keywords → Direkte Antwort

3. Tool-Ausführung (falls nötig)
   └── search_company, get_trust_score, etc.
   └── API-Aufrufe an die Datenbank

4. Antwort formatiert
   └── Backend → Frontend
   └── Im Chat-Widget anzeigen

Forensic Agent (On-Chain Analytics)

1. Benutzer fragt "Check balance of 0xd8dA..."
   └── Frontend → POST /api/ai/chat
   └── AI erkennt Wallet-Adresse-Keyword

2. Tool-Ausführung
   └── check_wallet-Funktion aufgerufen
   └── BigQuery-Abfrage an das crypto_ethereum-Dataset
   └── CoinGecko API für USD price

3. Antwort mit Kontext
   └── ETH balance + USD value + Etherscan link
   └── Backend → Frontend → Im Chat anzeigen

🔐 Sicherheit

• Authentifizierung: API-Key für Agent-Endpoints
• Autorisierung: IAM-basierte Zugriffskontrolle
• Verschlüsselung: Überall HTTPS, at-rest Encryption
• Secrets: Google Secret Manager

📊 Performance

Metrik	Ziel	Aktuell
API Response (cached)	unter 100ms	~50ms
API Response (DB)	unter 500ms	~200ms
Chat Response	unter 3s	~1.5s
Seitenladezeit	unter 2s	~1.2s