Build System Architecture

The MATIH build system supports three language ecosystems -- Java (Maven/Spring Boot), Python (pip/poetry/FastAPI), and TypeScript (npm/Vite/React) -- through a unified build.sh script that orchestrates compilation, testing, Docker image creation, and registry publishing for over 30 services.

Build Order

The build system follows a strict dependency order to ensure shared libraries are available before services that depend on them:

1. Commons Libraries
   ├── commons-java    (Maven install to local repo)
   ├── commons-python  (pip install -e)
   └── commons-typescript (npm install)

2. Control Plane Services (Java/Spring Boot)
   ├── iam-service
   ├── tenant-service
   ├── config-service
   ├── audit-service
   ├── notification-service
   ├── billing-service
   ├── platform-registry
   └── observability-api

3. Data Plane Services
   ├── Java: query-engine, catalog-service, semantic-layer, bi-service,
   │         data-plane-agent, governance-service
   ├── Python: ai-service, ml-service, data-quality-service,
   │           pipeline-service, ontology-service, ops-agent-service
   └── Node.js: render-service

4. Connectors (Java)
   ├── connector-sdk
   ├── postgresql-connector, mysql-connector
   ├── bigquery-connector, snowflake-connector
   ├── salesforce-connector
   └── s3-connector, gcs-connector, azure-blob-connector

5. Frontend Applications (TypeScript/React)
   ├── agentic-workbench, data-workbench, bi-workbench
   ├── ml-workbench, ops-workbench
   ├── control-plane-ui, data-plane-ui
   └── shared (component library)

Service Definitions

The build script maintains explicit service arrays for each category:

# Control Plane Services (Java/Spring Boot)
CONTROL_PLANE_JAVA_SERVICES=(
    "iam-service"
    "tenant-service"
    "config-service"
    "audit-service"
    "notification-service"
    "billing-service"
    "platform-registry"
    "observability-api"
)
 
# Data Plane Services (Python/FastAPI)
DATA_PLANE_PYTHON_SERVICES=(
    "ai-service"
    "ml-service"
    "data-quality-service"
    "pipeline-service"
    "ontology-service"
    "ops-agent-service"
    "ops-agent-service/infra-optimizer"
)
 
# Frontend Applications
FRONTEND_APPS=(
    "agentic-workbench"
    "data-workbench"
    "bi-workbench"
    "ml-workbench"
    "ops-workbench"
    "control-plane-ui"
    "data-plane-ui"
    "shared"
)

Build Flags

Flag	Description
`--all`	Build everything (default)
`--control-plane`	Build only control plane services
`--data-plane`	Build only data plane services
`--commons`	Build only commons libraries
`--connectors`	Build only connector modules
`--frontend`	Build only frontend applications
`--java`	Build only Java services
`--python`	Build only Python services
`--typescript`	Build only TypeScript services
`--skip-tests`	Skip running tests
`--test-only`	Only run tests (no build)
`--with-deps`	Start test dependencies (Redis, PostgreSQL)
`--push`	Push images to registry
`--tag TAG`	Docker image tag (default: latest)
`--registry REG`	Container registry (default: ghcr.io/matih)
`--parallel`	Build services in parallel
`--verbose`	Enable verbose output

Test Dependencies

When using --with-deps, the build system automatically manages test infrastructure:

# Redis container for cache testing
docker run -d --name matih-test-redis -p 6379:6379 redis:7-alpine
 
# PostgreSQL container for database testing
docker run -d --name matih-test-postgres \
    -p 5432:5432 \
    -e POSTGRES_USER=matih \
    -e POSTGRES_PASSWORD=matih \
    -e POSTGRES_DB=matih_test \
    postgres:16-alpine

The script verifies readiness before running tests (Redis via redis-cli ping, PostgreSQL via pg_isready) and stops containers after test completion.

Build Report

Every build produces a comprehensive summary:

Build Configuration:
  - Registry:        ghcr.io/matih
  - Tag:             latest
  - Skip Tests:      false
  - Test Only:       false
  - With Deps:       false
  - Push Images:     false

Build Results:
  [checkmark] iam-service
  [checkmark] tenant-service
  [checkmark] ai-service
  [x] ml-service

Build Summary: 3 succeeded, 1 failed

Test Results:
  Passed: 12
  Failed: 1

Pages in This Section

Page	Description
Build Script Deep Dive	Complete walkthrough of `scripts/build.sh`
Java Builds	Maven build process, commons-java, Spring Boot packaging
Python Builds	pip/poetry builds for FastAPI services
TypeScript Builds	npm/Vite builds for React workbenches
Docker Images	Multi-stage Dockerfiles, base images, optimization

Build System Build Script Deep Dive