Krow-workspace/docs/ARCHITECTURE/web.md

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
• Build Tool: Vite
• Styling: Tailwind CSS v4
• State Management: Redux Toolkit
• Data Fetching: TanStack Query (React Query)
• 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.