Chapter 2: Architecture Deep Dive

What This Chapter Covers

This chapter is organized into ten sections, each addressing a distinct architectural dimension of the platform. The sections are designed to be read sequentially for a complete understanding, but each section is also self-contained for reference.

Architecture at a Glance

The MATIH platform consists of 24 microservices distributed across 7 Kubernetes namespaces, communicating through a combination of synchronous REST APIs and asynchronous event streams. The platform processes natural language questions through a multi-agent AI pipeline that generates SQL, executes queries via Trino, and renders visualizations -- the "Intent to Insights" workflow.

                          +------------------+
                          |   Browser / CLI  |
                          +--------+---------+
                                   |
                          +--------v---------+
                          |  Kong API Gateway |
                          |   (Port 8080)     |
                          +--------+---------+
                                   |
                    +--------------+--------------+
                    |                             |
           +--------v---------+         +---------v--------+
           |  Control Plane   |         |   Data Plane     |
           |  (10 services)   |         |  (14 services)   |
           |  matih-control-  |         |  matih-data-     |
           |  plane namespace |         |  plane namespace  |
           +--------+---------+         +---------+--------+
                    |                             |
           +--------v---------+         +---------v--------+
           | PostgreSQL, Redis |         | PostgreSQL, Redis|
           | Kafka, ES         |         | Trino, Kafka     |
           +-------------------+         | Qdrant, Neo4j    |
                                         | ClickHouse, MinIO|
                                         +------------------+

Key Numbers

Two-Plane Architecture

The platform is divided into two distinct operational planes, each with its own deployment model, scaling strategy, and failure domain.

Control Plane

The Control Plane manages platform-level concerns that are shared across all tenants. It handles identity and access management, tenant provisioning, configuration distribution, billing, auditing, and infrastructure orchestration. All 10 Control Plane services are built with Java 21 and Spring Boot 3.2, deployed in the matih-control-plane namespace.

The Control Plane is tenant-aware but not tenant-specific -- it operates on metadata about tenants rather than on tenant data itself. When the Control Plane writes to its database, it stores tenant configuration, user profiles, and billing records -- never customer business data.

Data Plane

The Data Plane executes tenant-specific workloads including query execution, AI/ML inference, data pipeline orchestration, dashboard rendering, and data governance. Its 14 services span three technology stacks: Java/Spring Boot for data-intensive services, Python/FastAPI for AI/ML workloads, and Node.js for rendering. Data Plane services are deployed into per-tenant namespaces, providing namespace-level isolation.

The Data Plane processes, transforms, and analyzes actual customer data. Every query, every AI conversation, every ML training job runs within the tenant's Data Plane namespace, isolated from other tenants by Kubernetes NetworkPolicies and ResourceQuotas.

Namespace Organization

The platform uses seven Kubernetes namespaces to enforce logical and security boundaries:

In production, each tenant receives a dedicated namespace: matih-data-plane-{tenant-slug}. This namespace contains the tenant's Data Plane services, secrets, and resource quotas.

Commons Libraries

Shared functionality is extracted into four commons libraries that enforce consistency across service boundaries:

The commons-java library alone provides over 100 classes spanning API versioning, billing context, cache management, CDN integration, circuit breakers, database optimization, event streaming, exception handling, Kafka messaging, observability, and security -- all designed with multi-tenancy as a first-class concern.

Technology Stack Summary

Backend Technologies

Data Infrastructure

ML/AI Infrastructure

How to Read This Chapter

For architects and tech leads, start with Design Philosophy to understand the reasoning behind structural choices, then proceed to Service Topology for the interaction map, and Data Stores for storage architecture.

For backend developers, begin with Control Plane or Data Plane depending on which services you work with, then read Multi-Tenancy Architecture to understand context propagation and API Design for REST conventions.

For platform engineers, focus on API Gateway, Event-Driven Architecture, Data Stores, and Request Lifecycle to understand the infrastructure layer.

For anyone evaluating the platform, the Architecture Decision Records section provides the rationale behind every major technical decision, and Design Philosophy explains the trade-offs.

Related Chapters

• Security and Multi-Tenancy -- Authentication, authorization, and tenant isolation in depth
• Kubernetes and Helm -- Cluster topology, Helm chart structure, deployment patterns
• Observability -- Monitoring, distributed tracing, and alerting architecture
• CI/CD and Build System -- Pipeline stages and deployment workflow
• AI Service -- Multi-agent orchestrator deep dive
• Tenant Lifecycle -- Complete provisioning workflow