From 9e16429a6a010dbb7d588278a8577f1fbbd83d5d Mon Sep 17 00:00:00 2001 From: cyrus Date: Wed, 28 Jan 2026 16:27:36 +0530 Subject: [PATCH] Update documentation with current app state and design system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .claude/rules/08-frontend-guide.md | 111 +++++++++++++++++++---------- .claude/rules/12-design-system.md | 58 +++++++++------ CLAUDE.md | 55 +++++++++++++- 3 files changed, 164 insertions(+), 60 deletions(-) diff --git a/.claude/rules/08-frontend-guide.md b/.claude/rules/08-frontend-guide.md index 7db790fb3..e60fef893 100644 --- a/.claude/rules/08-frontend-guide.md +++ b/.claude/rules/08-frontend-guide.md @@ -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((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 (
-

{activeChannel?.name || 'Select Channel'}

- {user?.username} +

Chat

+
+ {profile?.username} +
+
); } diff --git a/.claude/rules/12-design-system.md b/.claude/rules/12-design-system.md index ec8b1ab87..f88052da8 100644 --- a/.claude/rules/12-design-system.md +++ b/.claude/rules/12-design-system.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index 662fa39dc..294fd5c5c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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