Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The flext-grpc platform is an enterprise-grade gRPC communication framework built on Clean Architecture and Domain-Driven Design (DDD) principles. It provides a high-performance, type-safe infrastructure for building microservices using the FLEXT ecosystem. The system is designed to provide a unified facade for managing gRPC server lifecycles, client connections, and complex streaming patterns while enforcing strict domain validation and state transitions.
The architecture emphasizes a clear separation of concerns, where core business logic is isolated from external technical implementations. This is achieved through layered organization: a pure Domain Layer for entities, an Application Layer for orchestration, and an Infrastructure Layer for external system integration.
Sources: src/README.md:1-50, src/flext_grpc/README.md:1-25
Architectural Layers
The project is structured into three primary layers to ensure maintainability and compliance with Clean Architecture standards.
Layer Definitions
| Layer | Files | Purpose |
|---|---|---|
| Domain | entities.py, models.py, types.py | Core business logic, immutable entities, and domain-specific rules. |
| Application | services.py, platform.py | Orchestration of business processes and use case implementations. |
| Infrastructure | api.py, settings.py, errors.py | Technical concerns including configuration, external integration, and error handling. |
Sources: src/README.md:38-70, src/flext_grpc/README.md:120-130
Dependency Flow
The system follows a strict "Infrastructure → Application → Domain" dependency direction, ensuring that the domain layer remains independent of technical implementation details.
The diagram shows the unidirectional dependency flow where outer layers depend on inner layers, preserving the purity of the Domain Layer.
Sources: src/README.md:75-85, src/flext_grpc/README.md:120-128
Core Components and Models
The system centers around several key domain entities and a unified facade for operation. These entities are rich models that include both data and behavioral validation.
Domain Entities
Domain entities in flext-grpc inherit from a base Entity class and often incorporate a StateMachine to manage lifecycles.
- FlextGrpcServer: Manages server state (Stopped, Starting, Running, Stopping), host/port binding, and service registration.
- FlextGrpcClient: Handles client-side connection management, channel delegation, and gRPC stubs.
- FlextGrpcChannel: Tracks the state of the underlying gRPC channel (Idle, Connecting, Ready).
- FlextGrpcStream: Manages different gRPC streaming patterns (Unary, Server-side, Client-side, Bidirectional).
Sources: src/flext_grpc/models.py:300-500, src/flext_grpc/README.md:30-55
Unified Facade: FlextGrpc
The FlextGrpc class acts as the primary entry point for developers. It abstracts complex orchestrations into simple factory and operation methods.
The diagram illustrates how the FlextGrpc facade simplifies interactions with the underlying domain entities and services.
Sources: examples/01_basic_usage.py:20-80, src/flext_grpc/README.md:70-85
State Management and Lifecycle
State transitions for servers and channels are strictly enforced using the Result (r) pattern to ensure "Railway-Oriented Programming," where failures are handled explicitly without exceptions for expected business logic errors.
Server Lifecycle State Machine
The server transitions through specific states during its execution lifecycle.
The server state machine ensures that operations like start() can only be initiated from a STOPPED state, preventing inconsistent execution.
Sources: src/flext_grpc/models.py:430-480, src/flext_grpc/README.md:40-45
Data Flow and Communication Patterns
The system supports four standard gRPC communication patterns, modeled within the FlextGrpcModels.Grpc.GrpcStream entity.
Operation Types
| Operation | Model Type | Description |
|---|---|---|
| Unary | UNARY | Single request, single response. |
| Server Streaming | SERVER_STREAMING | Single request, stream of responses. |
| Client Streaming | CLIENT_STREAMING | Stream of requests, single response. |
| Bidirectional | BIDIRECTIONAL | Stream of requests, stream of responses. |
Sources: src/flext_grpc/models.py:530-550, examples/02_advanced_usage.py:180-200
RPC Execution Flow
When a call is made through the platform, it follows a structured validation and execution path:
The sequence shows how validation is performed at the entity level before any network communication is attempted.
Sources: examples/01_basic_usage.py:75-95, src/flext_grpc/models.py:482-495
Configuration and Validation
Configuration is managed via FlextGrpcSettings, which utilizes Pydantic for runtime type safety and validation of network parameters, performance limits, and security settings.
Key Configuration Groups
- NetworkConfig: Handles host, port, and keepalive settings.
- PerformanceConfig: Manages thread pools, worker counts, and message size limits.
- SecurityConfig: Configures TLS/SSL certificates and authentication tokens.
- MonitoringConfig: Enables or disables metrics, tracing, and health checks.
Sources: src/flext_grpc/models.py:120-250, src/flext_grpc/README.md:88-105
Conclusion
The flext-grpc architecture provides a robust, layer-separated framework that prioritizes domain integrity and type safety. By utilizing the FlextGrpc facade and the Result pattern, it offers a predictable and enterprise-ready developer experience for building gRPC-based services within the FLEXT ecosystem. The combination of rich domain models and strict state machines ensures that system behavior remains consistent even in complex distributed environments.