Architecture

Overview

XBlast4D is built to modern microservices architecture standards. All components are developed and executed in separate Docker containers, providing:

• Service isolation
• Scalability
• Deployment reproducibility
• Operating system independence

Component Diagram

┌──────────────────────────────────────────────────────┐
│                External System Access                │
│         3000 (Frontend), 8001 (API Gateway)         │
│      MinIO: 9000 / 9001, Adminer: 8080 (optional)   │
└───────────────────────┬──────────────────────────────┘
                        │
               ┌────────▼────────┐
               │  Docker network │
               │ xblast4d-network│
               └────────┬────────┘
                        │
      ┌─────────────────┼───────────────────────────────────────┐
      │                 │                  │                    │
┌─────▼─────┐    ┌──────▼──────┐    ┌──────▼──────┐      ┌──────▼──────┐
│ Frontend  │    │ API Gateway │    │    MinIO    │      │  User Info   │
│   3000    │    │    8001     │    │ 9000/9001   │      │     8207     │
└───────────┘    └──────┬──────┘    └─────────────┘      └─────────────┘
                        │
      ┌─────────────────┼─────────────────────────────────────────────────────────────────────┐
      │                 │                │              │             │             │          │
┌─────▼─────┐   ┌───────▼──────┐  ┌──────▼─────┐ ┌──────▼─────┐ ┌─────▼─────┐ ┌────▼────┐ ┌──▼────────┐
│Import     │   │Blast Blocks  │  │Core Import │ │Block Model │ │Materials  │ │Wells    │ │Project    │
│Storage    │   │8202          │  │8203        │ │8204        │ │8209       │ │8205     │ │Manager    │
│8201       │   └──────────────┘  └────────────┘ └────────────┘ └───────────┘ └─────────┘ │8206      │
└───────────┘                                                                              └────┬──────┘
                                                                                               │
                                                                                       ┌───────▼──────┐
                                                                                       │ Viewer Data  │
                                                                                       │    8212      │
                                                                                       └──────────────┘

                 ┌───────────────────────────────┐
                 │ PostgreSQL, Redis, MinIO Mgr │
                 │      and service components  │
                 └───────────────────────────────┘

System Components

Frontend

• Framework: Next.js 15 (React 19)
• Languages: TypeScript, JavaScript
• Visualization: Three.js, WebAssembly (duckdb-wasm)
• Styling: Tailwind CSS
• Authentication: keycloak-js

API Gateway

• Framework: FastAPI
• Protocols: HTTP/REST, WebSockets
• Routing: Nginx (reverse proxy)

Computation Services (Backend)

• Language: Python 3.10
• Framework: FastAPI + uvicorn
• Async stack: asyncpg, SQLAlchemy
• Task queues: Celery + Redis
• File storage: MinIO

Infrastructure

Component	Purpose
PostgreSQL	Relational database
Redis	Caching and message broker
MinIO	S3-compatible object storage
Keycloak	Authentication and authorization management
Nginx	Reverse proxy and load balancing

Component Interaction

The frontend (Next.js) communicates with the backend via the API Gateway using HTTP/REST and WebSockets. External ports are usually published only on the loopback interface, while external access is organized through a system Nginx instance or another reverse proxy.

Computation tasks are distributed via Celery with Redis as the message broker. Results are stored in PostgreSQL; files are stored in MinIO.

Containerization

All components are orchestrated via Docker Compose:

• docker-compose.yml — base configuration
• docker-compose.prod.yml — operational configuration
• docker-compose.gpu.yml — GPU-accelerated configuration

info

There is no compilation in the traditional sense. Execution is handled through interpretation inside Docker containers. This guarantees reproducibility, security, and ease of installation.