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, Policy Service, Permissions Service |
| P1 | Onboarding UI | A dedicated flow for new account creation and tenant initialization. | Workflow Service |
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: Aggregation, Security, and Translation.
Technology Stack (Lean Approach)
For the initial phases, we are explicitly avoiding a complex Design System.
- Framework: React + Vite.
- Styling: Plain CSS (or simple modules).
- Goal: Speed of delivery over perfect consistency. We will build features first, and extract a design system only when patterns emerge and distinct teams require shared components.