# 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.