Request Lifecycle and Data Flow Overview
Every user interaction with the MATIH Platform follows a well-defined path through multiple system layers. This section traces the complete lifecycle of five key request flows, from browser to database and back. Understanding these flows is essential for debugging, performance optimization, and architectural reasoning.
Five Key Flows
| Flow | Starts At | Key Services | Typical Latency |
|---|---|---|---|
| Browser to Gateway | Browser | Kong Gateway, IAM Service | 2-200ms |
| Query Flow | BI Workbench | Query Engine, Trino, Semantic Layer | 50-5000ms |
| Agent Flow | Agentic Workbench | AI Service, Query Engine, Catalog | 1-8 seconds |
| Pipeline Flow | Data Workbench | Pipeline Service, Temporal, Spark/Flink | Minutes to hours |
| ML Flow | ML Workbench | ML Service, Ray, MLflow, Feast | Minutes to hours |
The Canonical Request Path
Every authenticated request follows this fundamental path through the platform:
Browser
|
v
Kong API Gateway (Port 8080)
| 1. Input validation
| 2. JWT validation and claims extraction
| 3. Rate limit check
| 4. Route matching
|
v
Backend Service
| 5. SecurityFilter (attack detection)
| 6. JwtAuthenticationFilter (token re-validation)
| 7. TenantContextFilter (context establishment)
| 8. Controller (request handling)
| 9. Service layer (business logic)
| 10. Repository (database access with tenant scope)
|
v
Response
| 11. Serialize response
| 12. Add security headers
| 13. Return through gateway
|
v
BrowserRequest Tracing
Every request is traceable end-to-end through two identifiers:
| Identifier | Set By | Purpose |
|---|---|---|
X-Request-ID | Kong Gateway | Unique per-request identifier |
X-Correlation-ID | Kong Gateway or client | Groups related requests across services |
These identifiers are propagated through HTTP headers, Kafka event headers, structured log entries, and OpenTelemetry span attributes.
Data Flow Patterns
| Pattern | Description | Used By |
|---|---|---|
| Read-through cache | Check Redis before querying PostgreSQL | Catalog, semantic models, config |
| Write-behind event | Write to database, then publish Kafka event | All state-changing operations |
| Streaming response | Server-Sent Events for token-by-token AI output | AI Service chat endpoints |
| Fan-out event | One event triggers multiple consumer actions | Audit, billing, notifications |
Related Sections
- Service Topology -- Service interaction map
- Event-Driven Architecture -- Asynchronous event flows
- API Design -- REST conventions and error handling