Update documentation with current app state and design system

- CLAUDE.md: Add comprehensive theme/design system section and recent changes summary - .claude/rules/12-design-system.md: Update color palette to reflect sophisticated ocean blue primary, sage success, amber warning, coral error colors - .claude/rules/08-frontend-guide.md: Update project structure showing HashRouter adoption, Redux state management, and 153 TypeScript files 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-28 13:32:23 +00:00 · 2026-01-28 16:27:36 +05:30
parent 5a0425c021
commit 9e16429a6a
3 changed files with 164 additions and 60 deletions
@@ -20,17 +20,52 @@ Frontend development guide for crypto-focused communication platform using moder
 - **Responsive Design**: Mobile-first approach with proper breakpoints
 - **Accessibility**: Focus rings, proper contrast, WCAG compliance ready

-## Structure
+## Current Project Structure (Updated)

 ```
 src/
-├── App.tsx             # Main application component
-├── App.css             # Application styles
-├── main.tsx            # Entry point
-├── vite-env.d.ts       # Vite type definitions
-└── assets/             # Static assets
+├── App.tsx                        # Main app with HashRouter + provider chain
+├── AppRoutes.tsx                  # Route definitions with protected/public routes
+├── main.tsx                       # Entry point with desktop deep link handling
+├── providers/                     # Context providers
+│   ├── SocketProvider.tsx         # Socket.io real-time communication
+│   ├── TelegramProvider.tsx       # Telegram MTProto integration
+│   └── UserProvider.tsx           # User state management
+├── store/                         # Redux Toolkit state management
+│   ├── index.ts                   # Store configuration with persist
+│   ├── authSlice.ts              # Authentication state
+│   ├── socketSlice.ts            # Socket connection state
+│   ├── userSlice.ts              # User profile state
+│   └── telegram/                  # Telegram state management
+├── services/                      # Service layer (singletons)
+│   ├── apiClient.ts              # HTTP REST client
+│   ├── socketService.ts          # Socket.io client
+│   └── mtprotoService.ts         # Telegram MTProto service
+├── lib/mcp/                       # Model Context Protocol system
+│   ├── transport.ts              # Socket.io JSON-RPC transport
+│   └── telegram/                  # 99 Telegram MCP tools
+├── pages/                         # Route components
+│   ├── Welcome.tsx               # Landing page
+│   ├── Login.tsx                 # Authentication
+│   ├── Home.tsx                  # Main dashboard
+│   └── onboarding/               # Multi-step onboarding
+├── components/                    # Reusable UI components
+│   ├── TelegramLoginButton.tsx   # OAuth login integration
+│   ├── ProtectedRoute.tsx        # Auth-gated routes
+│   ├── PublicRoute.tsx           # Guest-only routes
+│   └── ConnectionIndicator.tsx   # Status indicators
+└── utils/                         # Utilities and config
+    ├── config.ts                 # Environment variables
+    └── desktopDeepLinkListener.ts # Deep link handling
 ```

+### Recent Architecture Changes
+- **HashRouter**: Switched from BrowserRouter for better desktop app compatibility
+- **153 TypeScript files**: Comprehensive component library
+- **Provider chain**: Redux → PersistGate → Socket → Telegram → HashRouter → Routes
+- **MCP Integration**: 99 Telegram tools for AI-driven interactions
+- **Deep Link Auth**: Web-to-desktop handoff using `outsourced://` scheme
+
 ## React with Tauri

 ### Basic Component
@@ -216,48 +251,48 @@ switch (currentPlatform) {
 - **Headless UI** - Accessible, unstyled UI components
 - **Framer Motion** - Animation library for React

-### State & Data Management
- **Zustand** - Lightweight state management
- **TanStack Query** - Server state management & caching
- **React Hook Form** - Performant form handling
+### State & Data Management (Current Implementation)
+- **Redux Toolkit** - Currently implemented state management with persistence
+- **Redux Persist** - Persists auth and telegram state to localStorage
+- **Socket.io** - Real-time communication via socketService singleton
+- **MTProto Client** - Telegram integration via mtprotoService singleton
+- **MCP System** - 99 AI tools for Telegram interactions over Socket.io transport

-## State Management
-
-```bash
-npm install zustand
-```
+## Current State Management (Redux Toolkit)

 ```typescript
-import { create } from 'zustand';
+// Current implementation uses Redux Toolkit with these slices:
+import { useAppSelector, useAppDispatch } from '../store/hooks';

-// Example for crypto platform
-interface AppState {
-    user: User | null;
-    activeChannel: Channel | null;
-    messages: Message[];
-    setUser: (user: User) => void;
-    setActiveChannel: (channel: Channel) => void;
-    addMessage: (message: Message) => void;
-}
+// Auth state (persisted)
+const authState = useAppSelector((state) => state.auth);
+// { token: string | null, isOnboarded: boolean }

-const useStore = create<AppState>((set) => ({
-    user: null,
-    activeChannel: null,
-    messages: [],
-    setUser: (user) => set({ user }),
-    setActiveChannel: (channel) => set({ activeChannel: channel }),
-    addMessage: (message) => set((state) => ({
-        messages: [...state.messages, message]
-    })),
-}));
+// User state
+const userState = useAppSelector((state) => state.user);
+// { profile: UserProfile | null, loading: boolean, error: string | null }
+
+// Socket state
+const socketState = useAppSelector((state) => state.socket);
+// { isConnected: boolean, socketId: string | null }
+
+// Telegram state (selectively persisted)
+const telegramState = useAppSelector((state) => state.telegram);
+// Complex nested state with chats, messages, threads, auth status

 // Usage in component
 function ChatHeader() {
-    const { activeChannel, user } = useStore();
+    const { token } = useAppSelector((state) => state.auth);
+    const { profile } = useAppSelector((state) => state.user);
+    const { isConnected } = useAppSelector((state) => state.socket);
+
    return (
        <div className="flex items-center justify-between p-4">
-            <h1>{activeChannel?.name || 'Select Channel'}</h1>
-            <span>{user?.username}</span>
+            <h1>Chat</h1>
+            <div className="flex items-center gap-2">
+                <span>{profile?.username}</span>
+                <div className={`w-2 h-2 rounded-full ${isConnected ? 'bg-sage-500' : 'bg-coral-500'}`} />
+            </div>
        </div>
    );
 }
@@ -32,33 +32,49 @@ Small: text-sm (14px) - secondary information

 ## Color Palette - Trust & Professionalism

-### Primary Colors - Deep Trustworthy Blue
- **Primary-500**: `#0ea5e9` - Main brand color, conveys reliability
- **Primary-600**: `#0284c7` - Interactive states (buttons, links)
- **Primary-700**: `#0369a1` - Active states, emphasis
+### Primary Colors - Ocean Blue (Updated)
+- **Primary-500**: `#4A83DD` - Main brand color optimized for dark backgrounds
+- **Primary-600**: `#3D6DC4` - Interactive hover states
+- **Primary-700**: `#345A9F` - Active states, emphasis

-**Psychology**: Blue is universally associated with trust, security, and professionalism in financial apps.
+**Psychology**: Deep ocean blue builds trust and sophistication for crypto platforms.

-### Success Colors - Financial Green
- **Success-500**: `#22c55e` - Profit, positive transactions, confirmations
- **Success-600**: `#16a34a` - Interactive success states
+### Success Colors - Sage Green (Updated)
+- **Success-500**: `#4DC46F` - Refined success green for growth indicators
+- **Success-600**: `#3BA858` - Interactive success states

-**Psychology**: Green represents growth, wealth, and positive financial outcomes.
+**Psychology**: Sophisticated sage green represents growth and financial success.

-### Warning & Error Colors
- **Warning-500**: `#f59e0b` - Caution, pending states, important notices
- **Error-500**: `#ef4444` - Losses, errors, critical alerts
+### Warning & Error Colors (Updated)
+- **Warning-500**: `#E8A838` - Sophisticated amber for attention states
+- **Error-500**: `#F56565` - Soft coral red for professional error handling

-### Neutral Grays - Clean Interface
- **Neutral-50**: `#fafafa` - Background, light surfaces
- **Neutral-900**: `#171717` - Primary text, high contrast
- **Neutral-100-800**: Graduated scale for UI elements
+### Canvas Colors - Background Layers (Updated)
+- **Canvas-50**: `#FAFAF9` - Base background with subtle warmth
+- **Canvas-100**: `#F5F5F4` - Secondary background
+- **Canvas-150**: `#EDEDEC` - Tertiary background
+- **Canvas-200**: `#E5E5E3` - Card background
+- **Canvas-300**: `#D4D4D1` - Hover states

-### Crypto Accent Colors
- **Bitcoin**: `#f7931a` - BTC brand color
- **Ethereum**: `#627eea` - ETH brand color
- **Success**: `#00d4aa` - DeFi success indicators
- **Danger**: `#ff6b6b` - Risk warnings
+### Stone/Slate Neutrals - Text & UI Elements
+- **Stone-500**: `#78716C` - Mid-tone text
+- **Stone-900**: `#1C1917` - Primary text, high contrast
+- **Slate-400**: `#94A3B8` - Secondary text, data elements
+
+### Market Colors - Crypto Trading
+- **Bullish**: `#4DC46F` - Green for gains (matches sage)
+- **Bearish**: `#F56565` - Red for losses (matches coral)
+- **Neutral**: `#94A3B8` - Gray for no change
+- **Bitcoin**: `#F7931A` - Bitcoin orange
+- **Ethereum**: `#627EEA` - Ethereum purple
+- **Stablecoin**: `#5B9BF3` - Blue for stables
+
+### Accent Colors - Special Elements
+- **Lavender**: `#9B8AFB` - Premium features
+- **Mint**: `#6EE7B7` - Achievements
+- **Sky**: `#7DD3FC` - Notifications
+- **Rose**: `#FDA4AF` - Alerts
+- **Gold**: `#FCD34D` - Rewards

 ## Component Library

@@ -6,6 +6,35 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 Cross-platform crypto community communication platform built with **Tauri v2** (React 19 + Rust). Targets desktop (Windows, macOS) and mobile (Android, iOS). Features deep Telegram integration via MTProto, real-time Socket.io communication, and an MCP (Model Context Protocol) tool system for AI-driven Telegram interactions.

+## App Theme & Design System
+
+**Design Philosophy**: Premium, sophisticated crypto platform with calm, trustworthy aesthetic.
+
+### Color Palette
+- **Primary**: Ocean blue (`#4A83DD`) optimized for dark backgrounds
+- **Sage**: Success green (`#4DC46F`) for growth indicators
+- **Amber**: Warning (`#E8A838`) for attention states
+- **Coral**: Error (`#F56565`) soft professional red
+- **Canvas**: Background layers (`#FAFAF9` to `#D4D4D1`) with subtle warmth
+- **Market Colors**: Bullish green, bearish red, Bitcoin orange, Ethereum purple
+
+### Typography
+- **Primary**: Inter (premium font stack)
+- **Display**: Cabinet Grotesk for headings
+- **Mono**: JetBrains Mono for code
+- **Scale**: Sophisticated sizing with negative letter spacing for elegance
+
+### Component System
+- **Shadows**: Glow effects, subtle to float depth levels
+- **Animations**: Fade-in, slide-in, scale-in with cubic-bezier easing
+- **Border Radius**: Smooth system from `xs` (0.25rem) to `5xl` (2rem)
+- **Spacing**: Extended scale including custom values (4.5, 13, 15, etc.)
+
+### Current UI State
+- Uses HashRouter (not BrowserRouter) as seen in `App.tsx:1`
+- 153 TypeScript files total in src/
+- Sophisticated Tailwind config with custom color system and animations
+
 ## Commands

 ```bash
@@ -40,7 +69,7 @@ No test framework is currently configured. No ESLint or Prettier configuration e

 ### Provider Chain (App.tsx)

-The app wraps in this order: `Redux Provider` → `PersistGate` → `SocketProvider` → `TelegramProvider` → `BrowserRouter` → `AppRoutes`. This ordering matters because Socket.io and Telegram providers depend on Redux auth state.
+The app wraps in this order: `Redux Provider` → `PersistGate` → `SocketProvider` → `TelegramProvider` → `HashRouter` → `AppRoutes`. **Note**: Now uses HashRouter instead of BrowserRouter. This ordering matters because Socket.io and Telegram providers depend on Redux auth state.

 ### State Management (Redux Toolkit + Persist)

@@ -112,6 +141,29 @@ Set in `.env` (Vite exposes `VITE_*` prefixed vars):

 Production defaults are in `src/utils/config.ts`.

+## Recent Changes (Last 24 Hours)
+
+Key updates from recent commits:
+
+### Major Additions
+- **Type Casting Helpers**: Added for Telegram MTProto API (`5a0425c`)
+- **Onboarding Refactor**: Updated connection logic and steps (`bd1d240`)
+- **MCP Tools Enhancement**: Improved type safety and consistency across Telegram tools (`d0e1191`, `86cc53a`)
+- **App Structure**: Refactored MCPProvider integration (`d7d848d`)
+- **Big Integer Support**: Consistent handling across all Telegram MCP tools (`0abed4d`)
+
+### Design System Updates
+- **Lottie Animations**: Integrated into onboarding flow (`334673e`)
+- **Connection Components**: Added Telegram and Gmail connection indicators
+- **Routing**: Switched to HashRouter for better desktop app compatibility
+- **Theme**: Implemented sophisticated color system with premium crypto aesthetic
+
+### Component Structure
+- **153 TypeScript files** across `src/` directory
+- **Onboarding Flow**: Multi-step process with privacy, analytics, and connection steps
+- **Authentication**: Web-to-desktop handoff using `outsourced://` scheme
+- **Connection Management**: Telegram MTProto and Socket.io integration
+
 ## Key Patterns

 - **Node polyfills**: Vite config (`vite.config.ts`) polyfills `buffer`, `process`, `util`, `os`, `crypto`, `stream` for the `telegram` npm package which requires Node APIs.
@@ -119,6 +171,7 @@ Production defaults are in `src/utils/config.ts`.
 - **MCP tool files**: Each tool in `src/lib/mcp/telegram/tools/` exports a handler conforming to `TelegramMCPToolHandler` interface. Tool names are typed in `src/lib/mcp/telegram/types.ts`.
 - **Tauri IPC**: Frontend calls Rust via `invoke()` from `@tauri-apps/api/core`. Rust commands are registered in `generate_handler![]` macro.
 - **CORS workaround**: External HTTP requests from the WebView hit CORS. Use Rust `reqwest` via Tauri commands instead of browser `fetch()`.
+- **Hash Routing**: Uses HashRouter for desktop app compatibility and deep link handling.

 ## Platform Gotchas