92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# KROW Web Application Architecture
|
|
|
|
## 1. Overview
|
|
The KROW Web Application serves as the "Command Center" for the platform, catering to administrators, HR, finance, and client executives. It is a high-performance, scalable dashboard designed for complex data management and analytics.
|
|
|
|
## 2. Tech Stack
|
|
- **Framework**: [React 19](https://react.dev/)
|
|
- **Build Tool**: [Vite](https://vitejs.dev/)
|
|
- **Styling**: [Tailwind CSS v4](https://tailwindcss.com/)
|
|
- **State Management**: [Redux Toolkit](https://redux-toolkit.js.org/)
|
|
- **Data Fetching**: [TanStack Query (React Query)](https://tanstack.com/query/latest)
|
|
- **Backend Integration**: Firebase Data Connect + PostgreSQL
|
|
- **Language**: TypeScript
|
|
|
|
## 3. Monorepo & Project Structure
|
|
|
|
### Recommendation: Skip Nx
|
|
After evaluating `nx` for the KROW project, the recommendation is to **skip its adoption** at this stage.
|
|
|
|
**Reasoning:**
|
|
- **Existing Orchestration**: The root `Makefile` and `Melos` (for mobile) already provide a robust orchestration layer. Adding `nx` would introduce redundant complexity.
|
|
- **Heterogeneous Stack**: `nx` excels in JS/TS-heavy monorepos. Our project is a mix of Flutter (Dart) and React (TS), which reduces the native benefits of `nx`.
|
|
- **Maintainability**: The overhead of learning and maintaining `nx` configurations outweighs the current benefits for a project of this scale.
|
|
|
|
### Future Alternative: Turborepo
|
|
If caching and task orchestration become a bottleneck for the web/JS side, **Turborepo** is recommended as a lighter alternative that integrates seamlessly with our current `pnpm` setup.
|
|
|
|
### Final Project Structure (Unified)
|
|
```
|
|
/apps
|
|
/web # React Web Dashboard
|
|
/mobile # Flutter Mobile Apps (Melos monorepo)
|
|
/packages
|
|
/design-tokens # Shared Design System (TS/JSON)
|
|
/backend
|
|
/dataconnect # Shared GraphQL Schemas
|
|
/docs
|
|
/ARCHITECTURE # Architecture Documentation
|
|
/Makefile # Unified Command Orchestrator
|
|
```
|
|
|
|
## 4. Shared Design System
|
|
|
|
### Package: `@krow/design-tokens`
|
|
A dedicated package at `/packages/design-tokens` serves as the single source of truth for design constants across all platforms.
|
|
|
|
**Folder Structure:**
|
|
```
|
|
/packages/design-tokens
|
|
/src
|
|
/colors.ts # Color palette definitions
|
|
/typography.ts # Typography scale and font families
|
|
/index.ts # Main export entry
|
|
/package.json
|
|
/tsconfig.json
|
|
```
|
|
|
|
### Color Palette (Aligned with Mobile)
|
|
Based on `UiColors` from the mobile app:
|
|
- **Primary**: `#0A39DF` (Brand Blue)
|
|
- **Accent**: `#F9E547` (Accent Yellow)
|
|
- **Background**: `#FAFBFC`
|
|
- **Foreground**: `#121826`
|
|
- **Secondary**: `#F1F3F5`
|
|
- **Muted**: `#F1F3F5`
|
|
- **Destructive**: `#F04444` (Error Red)
|
|
- **Success**: `#10B981` (Success Green)
|
|
- **Border**: `#D1D5DB`
|
|
|
|
### Typography Scale (Aligned with Mobile)
|
|
- **Primary Font**: Instrument Sans
|
|
- **Secondary Font**: Space Grotesk
|
|
- **Scales**:
|
|
- **Display L**: 36px, Height 1.1
|
|
- **Display M**: 32px, Height 1.1
|
|
- **Title 1**: 18px, Height 1.5
|
|
- **Body 1**: 16px, Height 1.5
|
|
- **Body 2**: 14px, Height 1.5
|
|
|
|
### Implementation Strategy
|
|
1. **Definition**: Define tokens in TypeScript (or JSON) within `/packages/design-tokens`.
|
|
2. **Web Consumption**: Export tokens for use in `tailwind.config.ts` or as CSS variables.
|
|
3. **Mobile Consumption**: Use a script to generate `ui_colors.dart` and `ui_typography.dart` from the shared tokens to ensure perfect alignment.
|
|
|
|
## 5. Web Application Organization
|
|
The web application follows a **feature-based** modular architecture:
|
|
- `src/features/`: Contains feature-specific logic, components, and hooks (e.g., `billing`, `scheduling`, `admin`).
|
|
- `src/components/shared/`: Reusable UI components built with Tailwind.
|
|
- `src/hooks/`: Shared React hooks.
|
|
- `src/store/`: Redux slices for global state.
|
|
- `src/dataconnect-generated/`: SDK generated by Firebase Data Connect.
|