OpenSchema System Architecture
Comprehensive architectural documentation for the OpenSchema AI platform
System Overview
OpenSchema is a cloud-native microservices AI platform featuring:
- Backend APIs (Python/FastAPI)
- Frontend Applications (React/Next.js)
- Multi-LLM Support (OpenAI, OpenRouter)
- RAG with Knowledge Graph (PostgreSQL pgvector + Neo4j)
- Enterprise SSO (Keycloak)
- Observability Stack (MLflow + Grafana)
- GitOps Deployment (Kubernetes + ArgoCD)
Platform: openschema.ai (production), stg.openschema.ai (staging)
Architecture Diagram
High-Level Overview
┌─────────────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ Users / Clients │
│ (Browser / API Clients) │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ Routing Layer │
│ Traefik Ingress Controller │
│ • openschema.ai/* → Frontend (Next.js/React) │
│ • api.openschema.ai/v1/* → Backend APIs (FastAPI) │
│ • auth.openschema.ai → Keycloak (SSO) │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ Application Layer │
│ │
│ Frontend Services Backend Services │
│ • Next.js Apps • FastAPI Services │
│ • React+Vite Apps - router, auth, chat, rag, etc. │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ Infrastructure Layer │
│ │
│ Data Storage External Services │
│ • PostgreSQL (pgvector) • OpenAI API │
│ • Neo4j (Knowledge Graph) • OpenRouter API │
│ │
│ Identity & Observability Deployment & Orchestration │
│ • Keycloak (SSO/OIDC) • Kubernetes (Container Runtime) │
│ • MLflow (Experiment Tracking) • ArgoCD (GitOps) │
│ • Grafana (Monitoring) • GitHub Actions (CI/CD) │
│ • Prometheus (Metrics) • Docker (Containerization) │
└─────────────────────────────────────────────────────────────────────┘
Detailed Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ User / Client │
│ (Browser / API Clients) │
└────────────────────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Traefik Ingress Controller │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Route by Host & Path: │ │
│ │ • openschema.ai/* → Frontend UIs (Nginx/Next.js) │ │
│ │ • api.openschema.ai/v1/* → Backend APIs (FastAPI) │ │
│ │ • auth.openschema.ai → Keycloak │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
┌───────────────────────────────────┐ ┌──────────────────────────────────────┐
│ Frontend Layer │ │ Backend Layer │
│ (Kubernetes Pods) │ │ (Kubernetes Pods) │
├───────────────────────────────────┤ ├──────────────────────────────────────┤
│ │ │ │
│ Next.js Applications: │ │ FastAPI Services: │
│ ┌───────────────────────────────┐ │ │ ┌──────────────────────────────────┐ │
│ │ • admin-ui │ │ │ │ • router-api │ │
│ │ Admin Dashboard │ │ │ │ API Gateway & LLM Router │ │
│ │ /admin │ │ │ │ /v1/router │ │
│ │ │ │ │ │ ├─ Multi-provider routing │ │
│ │ • landing-ui │ │ │ │ ├─ API key failover │ │
│ │ Public Landing Page │ │ │ │ └─ Load balancing │ │
│ │ / │ │ │ │ │ │
│ │ │ │ │ │ • auth-api │ │
│ │ • landing-api-ui │ │ │ │ Authentication Service │ │
│ │ Enhanced Landing │ │ │ │ /v1/auth │ │
│ │ /landing-api │ │ │ │ └─ Keycloak integration │ │
│ │ │ │ │ │ │ │
│ │ • quarto-ui │ │ │ │ • chat-api │ │
│ │ Quarto Editor │ │ │ │ Conversation Management │ │
│ │ /quarto │ │ │ │ /v1/chat │ │
│ │ │ │ │ │ └─ MLflow logging (optional) │ │
│ │ • fslsm-ui │ │ │ │ │ │
│ │ FSLSM Frontend │ │ │ │ • rag-api │ │
│ └───────────────────────────────┘ │ │ │ RAG & Knowledge Graph │ │
│ │ │ │ /v1/rag │ │
│ React + Vite (Nginx): │ │ │ ├─ Document processing │ │
│ ┌───────────────────────────────┐ │ │ │ ├─ Vector embeddings │ │
│ │ • rag-ui │ │ │ │ ├─ Neo4j graph RAG │ │
│ │ RAG Interface │ │ │ │ └─ File management │ │
│ │ /rag │ │ │ │ │ │
│ │ ├─ File upload/management │ │ │ │ • quarto-api │ │
│ │ ├─ Graph visualization │ │ │ │ Quarto Integration │ │
│ │ └─ Chat interface │ │ │ │ /v1/quarto │ │
│ │ │ │ │ │ └─ Workspace management │ │
│ │ • multichat-ui │ │ │ │ │ │
│ │ Multi-Chat Interface │ │ │ │ │ │
│ │ /multichat │ │ │ │ │ │
│ └───────────────────────────────┘ │ │ │ • fslsm-api │ │
│ │ │ │ Domain Service │ │
│ Templates: │ │ │ │ │
│ • template-ui (React+Vite) │ │ │ • mcp-api │ │
│ • next-template-ui (Next.js) │ │ │ Model Context Protocol │ │
│ │ │ │ │ │
│ │ │ └──────────────────────────────────┘ │
│ │ │ │
│ │ │ Templates: │
│ │ │ • template-api │
└───────────────┬───────────────────┘ └──────────────┬───────────────────────┘
│ │
│ │
└─────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Infrastructure & Data Layer │
│ (Kubernetes + External) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Authentication & Identity: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Keycloak auth.openschema.ai │ │
│ │ ├─ Realms: openschema-prod, openschema-stg │ │
│ │ ├─ OAuth2 + OIDC │ │
│ │ ├─ JWT Token Issuance │ │
│ │ └─ Role-Based Access Control (RBAC) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Data Storage: │
│ ┌-─────────────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ PostgreSQL (Primary DB) │ │ Neo4j (Knowledge Graph) │ │
│ │ │ │ │ │
│ │ Extensions: │ │ Plugins: │ │
│ │ • pgvector (embeddings) │ │ • GenAI (vector similarity) │ │
│ │ • uuid-ossp │ │ • APOC (graph algorithms) │ │
│ │ │ │ │ │
│ │ Schemas (isolated): │ │ Graph Data: │ │
│ │ • auth_schema │ │ • Document nodes │ │
│ │ • chat_schema │ │ • Chunk nodes │ │
│ │ • router_schema │ │ • Relationships │ │
│ │ • rag_schema │ │ • Vector embeddings │ │
│ │ │ │ │ │
│ │ Used by: │ │ Used by: │ │
│ │ • auth-api (users) │ │ • rag-api (knowledge graph) │ │
│ │ • chat-api (conversations) │ │ • router-api (analytics) │ │
│ │ • router-api (keys, tokens) │ │ │ │
│ │ • rag-api (vectors, files) │ │ │ │
│ └────────────────────────-─────┘ └──────────────────────────────────────┘ │
│ │
│ External LLM Providers: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ OpenAI API api.openai.com/v1 │ │
│ │ ├─ Models: GPT-4, GPT-3.5-turbo │ │
│ │ ├─ Embeddings: text-embedding-3-small, text-embedding-ada-002 │ │
│ │ └─ Managed by: router-api (with failover) │ │
│ │ │ │
│ │ OpenRouter openrouter.ai/api/v1 │ │
│ │ ├─ Multi-model aggregator │ │
│ │ ├─ Models: Multiple providers │ │
│ │ └─ Fallback provider for router-api │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Monitoring & Observability: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ MLflow mlflow.openschema.ai │ │
│ │ ├─ Experiment tracking │ │
│ │ ├─ Request/response logging │ │
│ │ ├─ Metric collection (duration, tokens, status) │ │
│ │ └─ Used by: chat-api, quarto-api (optional integration) │ │
│ │ │ │
│ │ Grafana grafana.openschema.ai │ │
│ │ ├─ Metrics visualization & dashboards │ │
│ │ ├─ System monitoring (CPU, memory, network) │ │
│ │ ├─ Application metrics (requests, latency, errors) │ │
│ │ └─ Real-time alerting & reporting │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Deployment & Orchestration Layer │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Kubernetes Cluster: │
│ ┌─────────────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ Namespace: openschema-prod │ │ Namespace: openschema-stg (Staging) │ │
│ │ • Deployments (1-3 replicas) │ • Deployments (1 replica) │ │
│ │ • Services (ClusterIP/LB) │ │ • Services (ClusterIP/LB) │ │
│ │ • Ingress (Traefik) │ │ • Ingress (Traefik) │ │
│ │ • ConfigMaps & Secrets │ │ • ConfigMaps & Secrets │ │
│ │ • PVCs (PostgreSQL, Neo4j) │ │ • PVCs (PostgreSQL, Neo4j) │ │
│ └─────────────────────────────┘ └──────────────────────────────────────┘ │
│ │
│ GitOps (ArgoCD): │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ • Git Repository → Kustomize → Kubernetes │ │
│ │ • Auto-sync on manifest changes │ │
│ │ • Image auto-update (argocd-image-updater) │ │
│ │ • Health monitoring & self-healing │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ CI/CD Pipeline (GitHub Actions): │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Git Push → Build Docker Image → Push to cr.openschema.ai │ │
│ │ ↓ │ │
│ │ ArgoCD detects new image → Auto-deploy to K8s │ │
│ │ │ │
│ │ • main branch → Production (semantic version: 0.0.x) │ │
│ │ • develop branch → Staging (:stg tag) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Container Registry: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ cr.openschema.ai/openschemalabs/* │ │
│ │ • router-api:0.0.1, :stg │ │
│ │ • auth-api:0.0.1, :stg │ │
│ │ • rag-api:0.0.1, :stg │ │
│ │ • ... (all services) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Data Flow Examples
Authentication Flow
User → Frontend → Keycloak Login
↓
JWT Token Issued
↓
Frontend stores token (cookie)
↓
API Request → Header: Authorization: Bearer <JWT>
↓
Backend (KeycloakAuthorizationPlugin)
├─ Verify signature (Keycloak public key)
├─ Check expiration
├─ Extract user_id, roles
└─ Authorize request
↓
Execute & return response
LLM Request Flow
Frontend/API → router-api/v1/chat/completions
↓
Authenticate (JWT)
↓
Select provider (OpenAI/OpenRouter)
↓
Load balance across API keys
↓
Forward request
↓
┌──────────────┴──────────────┐
│ │
▼ ▼
OpenAI API OpenRouter API
│ │
└──────────────┬──────────────┘
↓
Success → Stream response
Error 429 → Rotate key → Retry
All keys fail → Failover to secondary
↓
Return response to client
(Optional: Log to MLflow)
RAG Query Flow
User uploads PDF → rag-ui → POST /v1/rag/neo4j/upload
↓
rag-api
├─ Extract text (PyPDF2)
├─ Chunk content
├─ Generate embeddings (OpenAI)
├─ Store vectors (PostgreSQL pgvector)
└─ Store graph (Neo4j)
User asks question → rag-ui → POST /v1/rag/neo4j/retrieve
↓
rag-api
├─ Generate query embedding
├─ Vector search (PostgreSQL)
├─ Graph search (Neo4j)
├─ Combine results (hybrid)
├─ Call LLM via router-api
└─ Return answer with citations
Tech Stack
Backend
Python 3.13
FastAPI 0.115+
SQLModel + asyncpg (PostgreSQL)
LangChain (LLM orchestration)
Neo4j (Knowledge graph)
Keycloak (Auth via python-jose)
Frontend
React 19 + Vite 7 / Next.js 16
TypeScript 5
Tailwind CSS 4
Radix UI (Components)
Zustand (State management)
Axios (HTTP client)
Infrastructure
Kubernetes (Orchestration)
ArgoCD (GitOps)
Traefik (Ingress)
Docker (Containers)
Nginx (Static serving)
GitHub Actions (CI/CD)
MLflow (Experiment tracking)
Grafana (Monitoring & dashboards)
Prometheus (Metrics collection)
Backend Services
| Service | Purpose | Key Tech | Ingress |
|---|---|---|---|
| router-api | API Gateway & LLM Router | LangChain, Multi-provider | /v1/router |
| auth-api | Authentication | Keycloak, JWT | /v1/auth |
| chat-api | Conversation Management | PostgreSQL, MLflow | /v1/chat |
| rag-api | RAG & Knowledge Graph | pgvector, Neo4j, LangChain | /v1/rag |
| quarto-api | Quarto Integration | Kubernetes client | /v1/quarto |
| fslsm-api | Domain Service | Minimal stack | /v1/fslsm |
| mcp-api | Model Context Protocol | FastMCP | /v1/mcp |
Key Features by Service
router-api:
- Multi-provider routing (OpenAI, OpenRouter)
- API key rotation & failover
- Load balancing
- Token management
auth-api:
- Keycloak OIDC login redirect and code exchange
- JWT validation for protected endpoints
- Token refresh and session management helpers
chat-api:
- Conversation title CRUD with auth guard
- Chat completions via OpenRouter (streaming/non-streaming)
- Conversation tree retrieval and CSV export
- Optional MLflow logging hooks for analytics
rag-api:
- Document processing (PDF, DOCX, XLSX, TXT, CSV)
- Vector embeddings (pgvector)
- Knowledge graph (Neo4j)
- Hybrid RAG retrieval
quarto-api:
- HTTP/WebSocket proxy to per-user Quarto workspaces
- Preserves live-reload behavior for editor sessions
- Header filtering and error handling for proxied traffic
fslsm-api:
- Serve FSLSM questionnaire definitions (v1)
- Score submissions into Active/Reflective, Sensing/Intuitive, Visual/Verbal, Sequential/Global
- Lightweight public endpoints for quiz delivery
mcp-api:
- FastMCP server exposing MCP tools over HTTP
- Example
greettool scaffold for extension - Simple host/port configuration for embedding in the platform
Frontend Services
| Service | Type | Purpose | Ingress |
|---|---|---|---|
| admin-ui | Next.js | Admin dashboard | /admin |
| landing-ui | Next.js | Public landing page | / |
| landing-api-ui | Next.js | Enhanced landing | /landing-api |
| rag-ui | React+Vite | RAG interface & graph viz | /rag |
| multichat-ui | React+Vite | Multi-chat interface | /multichat |
| quarto-ui | Next.js | Quarto editor | /quarto |
| fslsm-ui | Next.js | FSLSM frontend | /fslsm |
Key Features by Service
admin-ui:
- System administration dashboard
- User management
- Service configuration
- Analytics and monitoring overview
landing-ui:
- Public-facing homepage
- Product information
- Authentication gateway
- Marketing content
landing-api-ui:
- Enhanced landing experience
- API documentation showcase
- Interactive demos
- Developer onboarding
rag-ui:
- Document upload and management
- Knowledge graph visualization
- Interactive chat interface with RAG
- Citation and source tracking
multichat-ui:
- Multiple concurrent chat sessions
- Model comparison interface
- Chat history management
- Export and sharing capabilities
quarto-ui:
- Interactive Quarto editor
- Workspace management
- Real-time preview
- Collaboration features
fslsm-ui:
- Domain-specific frontend
- Custom workflows
- Specialized visualizations
Infrastructure Components
Databases
PostgreSQL
- User data, chat history, API keys
- Vector embeddings (pgvector extension)
- Schema per service isolation
Neo4j
- Knowledge graph for RAG
- Document relationships
- GenAI plugin + APOC
Authentication
Keycloak
- SSO/Identity Provider
- URL:
auth.openschema.ai - Realms:
openschema-prod,openschema-stg - JWT token validation
- Role-based access control (RBAC)
Container Registry
Harbor
- Private Docker registry for all service images
- Integrated with GitHub Actions build jobs and ArgoCD deploys
- Vulnerability scanning and image retention policies
- Robot accounts for CI/CD push/pull access
LLM Providers
- OpenAI: Direct API integration
- OpenRouter: Multi-model aggregator
- Managed by router-api with failover
Monitoring
MLflow
- URL:
mlflow.openschema.ai - Experiment tracking
- Request/response logging
- Automatic metric collection
Grafana
- URL:
grafana.openschema.ai - Metrics visualization & dashboards
- System monitoring (CPU, memory, network)
- Application metrics (requests, latency, errors)
- Real-time alerting & reporting
Deployment
Environments
| Environment | Namespace | Domain | Image Tag |
|---|---|---|---|
| Production | openschema-prod | openschema.ai | 0.0.x (semantic) |
| Staging | openschema-stg | stg.openschema.ai | :stg |
Deployment Flow
GitHub Push → GitHub Actions (Build) → Docker Push → ArgoCD (Auto-sync) → Kubernetes
Resource Configuration
Backend (typical):
Replicas: 1
CPU: 100m request, 500m limit
Memory: 128Mi request, 512Mi limit
Health: /ping endpoint
Frontend (typical):
Replicas: 1
CPU: 50m request, 200m limit
Memory: 64Mi request, 256Mi limit
Ingress Pattern
api.openschema.ai/v1/{service} → Backend APIs
openschema.ai/{path} → Frontend UIs
- Document Version: 1.0
- Last Updated: 2025-12-04