Merge dev

docs/ARCHITECTURE/web.md

@@ -0,0 +1,91 @@
+# 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.