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

Definition: Define tokens in TypeScript (or JSON) within /packages/design-tokens.
Web Consumption: Export tokens for use in tailwind.config.ts or as CSS variables.
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.

3.8 KiB Raw Blame History