Architecture Preview

The MATIH Enterprise Platform is built on a two-plane architecture that separates platform management (Control Plane) from tenant workload execution (Data Plane). This section provides a high-level overview of the architecture, preparing you for the comprehensive deep dive in Chapter 2.

Two-Plane Architecture

The platform is divided into two operationally independent planes, each with its own deployment model, technology stack, and failure domain.

Plane	Purpose	Technology	Deployment
Control Plane	Tenant management, identity, billing, configuration	Java 21, Spring Boot 3.2	Shared, Matih-operated
Data Plane	Query execution, AI/ML inference, BI, pipelines	Java, Python, Node.js	Per-tenant, customer cloud

+------------------------------------------------------------------+
|                        CONTROL PLANE                              |
|                  (Multi-tenant SaaS, Matih-operated)              |
+------------------------------------------------------------------+
| IAM | Tenant | Config | Notification | Audit | Billing | Registry|
| 8081|  8082  |  8888  |    8085      | 8086  |  8087   |  8084   |
+------------------------------------------------------------------+
                              |
                    Data Plane Agent (8085)
                              |
+------------------------------------------------------------------+
|                         DATA PLANE                                |
|                  (Per-tenant, Customer Cloud)                     |
+------------------------------------------------------------------+
| Query  | Catalog | Semantic |  BI  |  AI   |  ML  | Pipeline     |
| Engine | Service |  Layer   |Svc   |Service|Svc   | Service      |
|  8080  |  8086   |  8086    | 8084 | 8000  | 8000 |  8092        |
+------------------------------------------------------------------+

Control Plane Services

The Control Plane consists of 10 Java/Spring Boot 3.2 microservices deployed in the matih-control-plane Kubernetes namespace. These services manage platform-level concerns that are shared across all tenants.

Service	Port	Responsibility
`iam-service`	8081	Authentication, RBAC, JWT token management
`tenant-service`	8082	Tenant lifecycle, provisioning, namespace management
`config-service`	8888	Centralized configuration, feature flags
`notification-service`	8085	Multi-channel notification delivery
`audit-service`	8086	Immutable audit trail, compliance logging
`billing-service`	8087	Usage metering, subscription management
`observability-api`	8088	Metrics aggregation, health status
`infrastructure-service`	8089	Infrastructure provisioning, DNS management
`api-gateway`	8080	Request routing, JWT validation, rate limiting
`platform-registry`	8084	Service catalog, schema registry

The Control Plane is tenant-aware but not tenant-specific. It stores metadata about tenants (configuration, billing, user profiles) but never processes customer business data.

Data Plane Services

The Data Plane consists of 14 polyglot microservices deployed into per-tenant Kubernetes namespaces. These services execute the actual data processing, AI inference, and analytics workloads.

Service	Tech	Port	Responsibility
`ai-service`	Python/FastAPI	8000	LangGraph multi-agent orchestrator, text-to-SQL
`query-engine`	Java/Spring Boot	8080	Trino-based federated SQL execution
`bi-service`	Java/Spring Boot	8084	Dashboard management, widget rendering
`ml-service`	Python/FastAPI	8000	Model training, serving, experiment tracking
`catalog-service`	Java/Spring Boot	8086	Metadata management, schema resolution
`pipeline-service`	Java/Spring Boot	8092	Workflow orchestration via Temporal
`semantic-layer`	Java/Spring Boot	8086	Business metric definitions, MDL management
`data-quality-service`	Python/FastAPI	8000	Data profiling, quality checks
`render-service`	Node.js/Express	8098	Chart and PDF rendering
`governance-service`	Python/FastAPI	8080	Data classification, access policies
`ontology-service`	Python/FastAPI	8101	Business term resolution
`ops-agent-service`	Python/FastAPI	8080	AI-powered operations diagnostics
`data-plane-agent`	Java/Spring Boot	8085	Local health checking and lifecycle management

The Intent to Insights Flow

The core workflow of the platform transforms a natural language question into a data-driven answer:

User Question ("What was revenue last quarter?")
      |
      v
AI Service (multi-agent orchestrator)
      |
      +-- RouterAgent: classify intent
      +-- SQLAgent: generate SQL using schema context
      +-- Catalog Service: table/column metadata
      +-- Semantic Layer: business metric definitions
      +-- Vector Store: similar query examples
      |
      v
Generated SQL
      |
      v
Query Engine (Trino)
      |
      +-- Iceberg (lakehouse tables)
      +-- ClickHouse (OLAP analytics)
      +-- PostgreSQL (metadata)
      |
      v
Results
      |
      v
BI Service (visualization)
      |
      v
User Dashboard

Infrastructure Layer

The platform runs on a rich set of data infrastructure components:

Category	Technologies
Primary database	PostgreSQL 16
Caching and sessions	Redis 7
Event streaming	Apache Kafka (Strimzi Operator)
Federated SQL	Trino
OLAP analytics	ClickHouse, StarRocks
Vector embeddings	Qdrant, LanceDB
Knowledge graphs	Neo4j, Dgraph
Object storage	MinIO (S3-compatible)
Full-text search	Elasticsearch 8.11
ML infrastructure	MLflow, Ray, vLLM, Feast

Kubernetes Namespaces

The platform organizes workloads across seven Kubernetes namespaces:

Namespace	Purpose
`matih-system`	Core operators, CRDs, Strimzi, cert-manager
`matih-control-plane`	All 10 Control Plane services
`matih-data-plane`	Default Data Plane services (per-tenant in production)
`matih-observability`	Prometheus, Grafana, Tempo, Loki
`matih-monitoring-control-plane`	Control Plane monitors and alerts
`matih-monitoring-data-plane`	Data Plane monitors and alerts
`matih-frontend`	React workbench applications

In production, each tenant receives a dedicated namespace following the pattern matih-data-plane-:tenant-slug, providing full namespace-level isolation.

Next Steps

This architecture preview establishes the structural foundation. For the complete deep dive into every layer, service interaction, and design decision, continue to Chapter 2: Architecture Deep Dive.

Key Terminology Getting Started Guide