Architecture Reference

Detailed technical architecture for DevOps and platform teams

High-Level Architecture

Core Services

Frontend Applications

Explorer (React + Vite)

Visual query builder interface
Real-time graph exploration
Advanced visualizations (node-link, charts, maps)
WebSocket support for live updates

Graph Designer (Svelte)

Data import and ETL configuration
Schema mapping interface
Import job monitoring
Lightweight and performant

Backend Microservices

Service	Runtime	Purpose
Client Gateway	Node.js/Bun	API entry point, auth, routing
Database Service	Node.js/Bun	Graph queries, schema extraction
ML Service	Python	ML algorithms, graph analytics
LLM Service	Python	NLP, AI insights
Graph Importer	Node.js/Bun	ETL pipeline, data import

Client Gateway

API entry point for all client requests
Authentication and session management (Better Auth)
Request routing and load balancing
WebSocket proxy
REST API endpoints

Database Service

Connects to external graph databases
Query translation (visual query → Cypher/Gremlin)
Schema extraction and parsing
Query optimization and execution
Result parsing and transformation
Supports: Neo4j, Memgraph, PostgreSQL

ML Service

Machine learning algorithms execution
Graph-specific algorithms (PageRank, community detection)
Data augmentation
Result enrichment for visualizations

LLM Service

Natural language query processing
AI-powered insights generation
Query recommendations
Documentation generation

Graph Importer

ETL pipeline for data import
CSV, Excel, JSON parsing
Data transformation and validation
Bulk import operations
Import job management

Data Layer

PostgreSQL (Metadata Storage)

Purpose: Application metadata, not graph data

Stores:

User accounts and organizations
Graph schemas and configurations
Import job metadata
Query history
Application settings

Requirements:

PostgreSQL 14+
10 GB storage minimum
Connection pooling recommended

Redis (Caching & Sessions)

Purpose: Performance and session management

Stores:

Session storage
Query result caching
Schema caching
Pub/sub for real-time updates
Rate limiting data

Requirements:

Redis 7+
2 GB RAM minimum
Persistence optional (sessions)

RabbitMQ (Message Queue)

Purpose: Asynchronous processing

Features:

Asynchronous job processing
Service-to-service communication
Event-driven architecture
Task queuing for long-running operations

Exchanges:

ui-direct-exchange - Frontend requests
ml-direct-exchange - ML job processing
import-exchange - Import jobs

Requirements:

RabbitMQ 3.12+
Clustering recommended for HA

Graph Database (External)

Your database - GraphPolaris connects to it

Supported:

Neo4j (4.4+, 5.x)
Memgraph

Service Communication

Communication Patterns:

Synchronous: REST API for user-facing operations
Asynchronous: RabbitMQ for background processing
Real-time: WebSockets for live updates
Caching: Redis for frequently accessed data

Technology Stack

Frontend

Technology	Purpose
React 18+	Explorer UI
Svelte	Designer UI
Vite	Build tool
TypeScript	Type safety
D3.js	Visualizations
MapBox	Geographic vis

Backend

Technology	Purpose
Bun	Runtime
TypeScript	Language
Python 3.11+	ML/LLM services
Better Auth	Authentication
Drizzle ORM	PostgreSQL

Infrastructure

Technology	Purpose
Kubernetes	Orchestration
Istio	Service mesh
Helm	Package management
ArgoCD	GitOps deployment
Prometheus	Monitoring

Scaling Characteristics

Stateless Services (Horizontally Scalable)

All application services are stateless:

Frontend applications
Client Gateway
Database Service
ML Service
LLM Service
Graph Importer

Scaling Method: Add more pods/replicas via Kubernetes HPA

Stateful Services

Service	Scaling Strategy
PostgreSQL	Read replicas, connection pooling
Redis	Cluster mode or Sentinel
RabbitMQ	Cluster with mirrored queues

Autoscaling Configuration

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: client-gateway-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: client-gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Resource Requirements

Minimum (Development/Testing)

Component	CPU	Memory	Storage
Client Gateway	500m	512Mi	-
Database Service	500m	512Mi	-
ML Service	1000m	2Gi	-
LLM Service	1000m	2Gi	-
PostgreSQL	500m	1Gi	10Gi
Redis	250m	512Mi	1Gi
RabbitMQ	500m	512Mi	5Gi

Production (Recommended)

Component	CPU	Memory	Storage	Replicas
Client Gateway	2000m	2Gi	-	3+
Database Service	2000m	2Gi	-	3+
ML Service	4000m	8Gi	-	2+
LLM Service	4000m	8Gi	-	2+
PostgreSQL	2000m	4Gi	50Gi	2+
Redis	1000m	2Gi	10Gi	3
RabbitMQ	1000m	2Gi	20Gi	3

Health Checks

All services expose health endpoints:

Endpoint	Purpose	Used By
`/health`	Liveness	Kubernetes liveness probe
`/ready`	Readiness	Kubernetes readiness probe
`/metrics`	Prometheus	Monitoring

Probe Configuration

livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
  failureThreshold: 3

Container Images

Registry: graphpolaris.azurecr.io

Image	Description
`graphpolaris-frontend`	Explorer UI
`graphdesigner`	Designer UI
`client-gateway`	API Gateway
`database-service`	Query engine
`ml-service`	ML processing
`llm-service`	AI/NLP
`graphimporter`	Data import