Skip to content

Architecture Goals

This document outlines the primary architectural goals of the geOrchestra Gateway, which guide its design, implementation, and evolution.

Primary Goals

1. Security

Goal: Provide a secure, centralized authentication and authorization layer for the entire geOrchestra platform.

Rationale: As the entry point for all user interactions, the Gateway must enforce robust security controls to protect sensitive geospatial data and services.

Approaches:

  • Implement multiple authentication methods (LDAP, OAuth2/OpenID Connect, Header pre-authentication)
  • Enforce role-based access control for all services
  • Apply security best practices (HTTPS, secure headers, CSRF protection)
  • Sanitize and validate all user input and headers
  • Support password policy enforcement through LDAP

2. Flexibility and Extensibility

Goal: Create a highly configurable and extensible platform that can adapt to different deployment scenarios and requirements.

Rationale: geOrchestra installations vary widely in their specific requirements, integration needs, and deployment environments.

Approaches:

  • Modular architecture with clear extension points
  • External configuration through the data directory
  • Service-based design with well-defined interfaces
  • Support for plugin development through Spring's extension mechanisms
  • Customizable authentication and user mapping

3. Modern Reactive Architecture

Goal: Utilize a reactive programming model to ensure high throughput and efficient resource utilization.

Rationale: Gateway performance directly impacts the user experience of the entire platform, and reactive programming provides better scalability under high load.

Approaches:

  • Built on Spring WebFlux and Project Reactor
  • Non-blocking I/O throughout the application
  • Reactive data access where possible
  • Asynchronous event handling via RabbitMQ

4. Observability

Goal: Provide comprehensive monitoring, logging, and troubleshooting capabilities.

Rationale: Operational visibility is critical for maintaining a reliable production service and quickly identifying issues.

Approaches:

  • Structured JSON logging with configurable detail levels
  • MDC propagation in reactive contexts
  • Spring Boot Actuator endpoints for monitoring
  • Correlation IDs across service boundaries
  • Access logging with pattern-based filtering

5. Developer Experience

Goal: Create a codebase that is easy to understand, extend, and maintain.

Rationale: An approachable codebase encourages community contributions and ensures long-term sustainability.

Approaches:

  • Clear package structure and separation of concerns
  • Comprehensive documentation
  • Consistent coding standards
  • Extensive test coverage
  • Simplified local development setup

Secondary Goals

1. Backward Compatibility

Goal: Maintain compatibility with existing geOrchestra services and deployment patterns.

Rationale: Organizations upgrading from the previous security-proxy should be able to do so with minimal disruption.

Approaches:

  • Compatible header schemes for service communication
  • Similar configuration structure where appropriate
  • Support for legacy authentication patterns

2. Performance

Goal: Minimize latency and resource utilization.

Rationale: The Gateway is in the critical path for all user requests, making its performance impact multiplicative.

Approaches:

  • Efficient proxy implementation using Spring Cloud Gateway
  • Caching of authentication and authorization decisions where appropriate
  • Connection pooling for backend services
  • Optimized filter chain processing

3. Interoperability

Goal: Support integration with external systems and identity providers.

Rationale: Many organizations need to integrate geOrchestra with existing identity management systems.

Approaches:

  • Support for standard protocols (OAuth2, OpenID Connect, LDAP)
  • Flexible header-based pre-authentication for proxy integration
  • Event-driven architecture for system integration

4. Cloud-Native Design

Goal: Ensure the Gateway works well in containerized and orchestrated environments.

Rationale: Modern deployments increasingly use containers and orchestration platforms like Kubernetes.

Approaches:

  • Stateless design where possible
  • Externalized configuration
  • Health checks and readiness probes
  • Graceful startup and shutdown
  • Support for horizontal scaling