Skip to main content

0012: Third-Party Integration Strategy

Date: 2025-08-11

Status: Revised

Context​

The Citadel platform aims to be extensible, allowing third-party developers and ecosystem partners to build solutions that interact with the platform. It is crucial to clarify the mechanism for this interaction, especially concerning the shell-app. The shell-app is considered a first-party application or a fork thereof, primarily serving internal or closely controlled use cases. Third-party solutions are not intended to be directly embedded or integrated into the shell-app's UI at build-time or runtime via mechanisms like Micro-Frontends.

Decision​

Third-party integration with the Citadel platform will primarily occur through API-first interfaces, event-driven architectures, and webhooks. Direct integration of third-party Micro-Frontends (MFEs) into the shell-app via Module Federation or similar UI embedding techniques is explicitly not the chosen strategy.

Instead:

  1. API-First Interaction: Third-party applications will interact with Citadel services through well-defined, versioned APIs (e.g., via the API Gateway).
  2. Event-Driven Communication: Key business events within the Citadel platform will be published, allowing third parties to subscribe and react to changes.
  3. Webhooks: Third-party systems can register webhooks to receive notifications for specific events, enabling real-time data synchronization and reactive workflows.
  4. Independent UI Development: Third-party developers are responsible for building and hosting their own user interfaces. These UIs will consume Citadel APIs and events, providing a decoupled and flexible integration model. The shell-app will not serve as a host for external UIs.
  5. No Framework Enforcement: The shell-app itself is framework-agnostic and does not expose any framework-specific extension points. This reinforces the decision to rely on APIs and events, as there is no common UI framework to build upon for integration.

Consequences​

Positive​

  • Clear Separation of Concerns: Maintains a strict boundary between first-party applications (like shell-app) and third-party solutions, reducing complexity and interdependencies.
  • Enhanced Security: Reduces the attack surface by avoiding direct embedding of external code into core applications. All interactions are mediated through controlled API endpoints and event channels.
  • Framework Agnostic: Third-party developers have complete freedom to choose their preferred technology stack for their applications and UIs, as long as they adhere to the defined API and event contracts.
  • Scalability and Resilience: Decoupled integration points improve the overall scalability and resilience of the platform, as failures in third-party UIs do not directly impact the shell-app.
  • Simplified Deployment: The shell-app's deployment cycle is independent of third-party UI development and deployment.

Negative​

  • No Direct UI Embedding: Third-party applications cannot directly extend or customize the shell-app's user interface. Any UI integration must be achieved by linking to or embedding independent third-party applications.
  • Potential for Inconsistent UX: Without a shared UI library or direct embedding, maintaining a consistent user experience across first-party and third-party applications requires careful design guidelines and adherence by third-party developers.
  • Increased Development Effort for Third Parties: Third-party developers must build and host their entire UI, rather than leveraging a host application for rendering.