Citadel: UI/UX & Frontend Strategy

This document outlines the strategy for building a modern, scalable frontend architecture for the Citadel platform.

1. Vision & Architecture

Vision: To create a cohesive, fast, and responsive user experience composed of independent frontend applications that can be developed, tested, and deployed autonomously.

Architecture: Micro-Frontends via Module Federation

• We will adopt a Micro-Frontends architecture. Each business domain (e.g., Invoicing, Stock) will have its own dedicated frontend team and application.
• A "shell" or "host" application will provide the main navigation, header, footer, and authentication state.
• Individual micro-frontends (e.g., the Invoice List page, the Stock Ledger report) will be loaded into the shell at runtime.
• Webpack Module Federation is the recommended technology for this. It is a mature, framework-agnostic solution for dynamically loading code from other applications, allowing for true runtime composition.

2. UI/UX Priority

The frontend strategy prioritizes building the core administrative and developer-facing interfaces for the platform itself. Product-specific applications (like Invoicing or CRM) are considered separate entities to be built on top of the platform.

Priority	Frontend Application	Description	Backend Dependencies
P0	Shell Application	The main application frame. Handles login, top-level navigation, and tenant selection.	IAM Service, API Gateway
P1	Admin Portal	A core administrative UI for managing tenants, users, roles, and other master data. This is the primary interface for system administrators.	Admin Portal BFF
P1	Developer Portal	A self-service portal for third-party developers to register their applications, manage OAuth2 clients, and access API documentation.	Developer Portal BFF

Future Product Applications (Examples)

The following applications are examples of products that can be built on the Citadel platform, but they are not part of the core platform's frontend development roadmap.

• Invoicing App: A complete user journey for creating, viewing, and managing AR/AP invoices.
• Stock Management App: Interfaces for stock entries, transfers, and viewing the stock ledger.
• CRM App: User interfaces for managing leads, opportunities, and customer relationships.

3. Key Decisions & Strategy

Backend-for-Frontend (BFF) Pattern

While the API Gateway serves as a general entry point, each micro-frontend team will be responsible for an optional Backend-for-Frontend (BFF).

• What it is: A small, dedicated server-side component that sits between a specific UI (like the mobile app or the Invoicing web app) and the downstream microservices.
• Why it's useful:
  1. Aggregation: It can make multiple calls to downstream services (Invoicing, Products) and aggregate the data into a single payload, optimized for that specific UI view. This simplifies frontend logic and reduces the number of network requests from the browser.
  2. Security: It provides an extra security layer. The frontend talks to the BFF, and the BFF (which can hold more secure credentials like API keys) talks to the backend services.
  3. Translation: It can translate generic backend API responses into a format that is specific to the needs of the web, mobile, or voice app, preventing the UI from becoming bloated with business logic.

Centralized Design System

A centralized, shared component library (Design System) is non-negotiable for this project's success.

• Goal: To ensure a consistent look, feel, and user experience across all micro-frontends, regardless of which team builds them.
• Implementation:
  • A dedicated team will own the Design System.
  • It will contain reusable, styled, and accessible components like Buttons, Data Tables, Date Pickers, Form Inputs, etc.
  • It will be developed in its own repository and published as a versioned private package (e.g., to NPM or a private registry).
  • All frontend application teams will consume this package as a dependency.
• Benefit: This enforces consistency, prevents duplicated effort, and dramatically accelerates the development of new features and applications.

---