From f2704e44cdaa3c262951dc8583a960ee28a6cbbb Mon Sep 17 00:00:00 2001 From: cyrus Date: Mon, 2 Feb 2026 16:39:56 +0530 Subject: [PATCH] Update CLAUDE.md with new features, state slices, and code quality tools - Document additions: Redux aiSlice, skillsSlice, teamSlice, and architecture updates - Add ESLint, Prettier integrations with Husky hooks and GitHub workflows - Update development commands from npm to yarn for consistency - Expand key user groups and revise target audiences - Include enhanced project structure, build outputs, and CI/CD updates --- .claude/rules/01-project-overview.md | 48 ++++++++--- .claude/rules/02-development-commands.md | 72 ++++++++++------ .claude/rules/08-frontend-guide.md | 59 ++++++++++--- CLAUDE.md | 101 +++++++++++++++++------ 4 files changed, 209 insertions(+), 71 deletions(-) diff --git a/.claude/rules/01-project-overview.md b/.claude/rules/01-project-overview.md index 31e232674..d80498191 100644 --- a/.claude/rules/01-project-overview.md +++ b/.claude/rules/01-project-overview.md @@ -11,9 +11,10 @@ This project is a **crypto-focused communication platform** built with Tauri v2, ## Target Users -- Traders, Yield Farmers, Investors -- Researchers, KOLs, Developers -- General crypto community members +- **Crypto Professionals**: Traders, Yield Farmers, Investors +- **Researchers & Analysts**: KOLs, Developers, Researchers +- **Teams & Organizations**: Collaborative workspaces for crypto projects +- **General Community**: Crypto enthusiasts and community members ## Technology Stack @@ -28,9 +29,21 @@ This project is a **crypto-focused communication platform** built with Tauri v2, | Components | Headless UI | Latest | Accessible components | | Animation | Framer Motion | Latest | Smooth animations | | **State & Data** | -| State Management | Zustand | Latest | Lightweight state | +| State Management | Redux Toolkit | Latest | Predictable state mgmt | +| State Persistence | Redux Persist | Latest | State rehydration | | Data Fetching | TanStack Query | Latest | Server state management | | Form Handling | React Hook Form | Latest | Form validation | +| **AI & Intelligence** | +| AI Memory | Custom System | Latest | Context & learning | +| Entity Graph | Neo4j | Latest | Knowledge relationships | +| Embeddings | OpenAI | Latest | Semantic search | +| **Communication** | +| Real-time | Socket.io | Latest | Live messaging | +| Telegram Integration | MTProto | Latest | Deep Telegram access | +| MCP Protocol | JSON-RPC 2.0 | Latest | AI tool execution | +| **Team & Skills** | +| Skills Platform | GitHub Sync | Latest | Dynamic skill loading | +| Team Management | REST API | Latest | Multi-user collaboration| | **Backend Core** | | Language | Rust | 1.93.0 | Performance & safety | | Framework | Tauri | 2.x | Cross-platform apps | @@ -45,25 +58,40 @@ This project is a **crypto-focused communication platform** built with Tauri v2, ## Project Structure ``` -tauri-crossplatform-app/ +frontend-runner-alphahuman/ ├── .claude/ # Claude AI configuration │ ├── rules/ # Modular documentation │ └── agents/ # Subagent configurations ├── src/ # React frontend source +│ ├── lib/ # Core libraries +│ │ ├── ai/ # AI system (memory, constitution, entities) +│ │ └── mcp/ # Model Context Protocol implementation +│ ├── components/ # React components +│ │ └── settings/ # Settings modal system +│ ├── store/ # Redux state management +│ ├── services/ # API clients and services +│ └── pages/ # Application pages ├── src-tauri/ # Rust backend source │ ├── gen/ # Generated platform code │ │ ├── android/ # Android project │ │ └── apple/ # iOS/macOS project │ ├── icons/ # Application icons │ └── src/ # Rust source code +├── skills/ # Skills submodule (GitHub synced) ├── public/ # Static assets +│ └── lottie/ # Animation files +├── .github/workflows/ # CI/CD pipelines └── dist/ # Build output ``` ## Key Configuration Files -- `tauri.conf.json` - Tauri configuration -- `Cargo.toml` - Rust dependencies -- `package.json` - Node.js dependencies -- `vite.config.ts` - Vite build configuration -- `tsconfig.json` - TypeScript configuration +- `tauri.conf.json` - Tauri configuration (app identifier: com.alphahuman.app) +- `Cargo.toml` - Rust dependencies and workspace configuration +- `package.json` - Node.js dependencies and scripts +- `vite.config.ts` - Vite build configuration with Node.js polyfills +- `tsconfig.json` - TypeScript configuration with strict settings +- `eslint.config.js` - ESLint configuration with ES modules +- `.prettierrc` - Code formatting rules +- `.husky/` - Git hooks for pre-commit/pre-push quality checks +- `CLAUDE.md` - Main project documentation for Claude Code diff --git a/.claude/rules/02-development-commands.md b/.claude/rules/02-development-commands.md index d6f18aaad..221b7c841 100644 --- a/.claude/rules/02-development-commands.md +++ b/.claude/rules/02-development-commands.md @@ -13,53 +13,75 @@ Before running any commands, ensure you have: ### Desktop Development ```bash -# Start development server (hot-reload) -npm run tauri dev +# Frontend dev server only (port 1420) +yarn dev -# Build for production -npm run tauri build +# Desktop dev with hot-reload (starts Vite + Tauri) +yarn tauri dev + +# Production build (TypeScript compile + Vite build + Tauri bundle) +yarn tauri build + +# Debug build with .app bundle (required for deep link testing on macOS) +yarn tauri build --debug --bundles app +yarn macos:dev ``` ### Android Development ```bash # Initialize Android project (first time) -npm run tauri android init +yarn tauri android init # Start Android development -npm run tauri android dev +yarn tauri android dev # Build Android APK/AAB -npm run tauri android build +yarn tauri android build ``` ### iOS Development ```bash # Initialize iOS project (first time) -npm run tauri ios init +yarn tauri ios init # Start iOS development -npm run tauri ios dev +yarn tauri ios dev # Build iOS app -npm run tauri ios build +yarn tauri ios build ``` ### Frontend Only ```bash # Install dependencies -npm install +yarn install # Start Vite dev server only -npm run dev +yarn dev # Build frontend only -npm run build +yarn build # Preview production build -npm run preview +yarn preview +``` + +### Code Quality + +```bash +# Run linting and formatting checks +yarn lint +yarn format + +# TypeScript compilation check +yarn typecheck + +# Rust checks +cargo check --manifest-path src-tauri/Cargo.toml +cargo clippy --manifest-path src-tauri/Cargo.toml ``` ## Stopping Development Servers @@ -67,7 +89,7 @@ npm run preview ### Desktop (Tauri Dev) ```bash -# In the terminal running `npm run tauri dev`: +# In the terminal running `yarn tauri dev`: Ctrl + C # If process is stuck, force kill: @@ -86,7 +108,7 @@ taskkill /PID /F # Kill by PID ### Android Dev Server ```bash -# In the terminal running `npm run tauri android dev`: +# In the terminal running `yarn tauri android dev`: Ctrl + C # If emulator/device is stuck: @@ -108,7 +130,7 @@ taskkill /F /IM java.exe # Kills Gradle processes ### iOS Dev Server ```bash -# In the terminal running `npm run tauri ios dev`: +# In the terminal running `yarn tauri ios dev`: Ctrl + C # If simulator is stuck: @@ -129,7 +151,7 @@ pkill -f "cargo" ### Frontend Only (Vite) ```bash -# In the terminal running `npm run dev`: +# In the terminal running `yarn dev`: Ctrl + C # If port 1420 is still occupied: @@ -156,10 +178,10 @@ Get-Process | Where-Object {$_.ProcessName -match "tauri|vite|cargo|node"} | Sto ## Build Targets -| Platform | Command | Output | -| -------- | ----------------------------- | ------------------- | -| Windows | `npm run tauri build` | `.msi`, `.exe` | -| macOS | `npm run tauri build` | `.dmg`, `.app` | -| Linux | `npm run tauri build` | `.deb`, `.AppImage` | -| Android | `npm run tauri android build` | `.apk`, `.aab` | -| iOS | `npm run tauri ios build` | `.ipa` | +| Platform | Command | Output | +| -------- | ------------------------------ | ------------------- | +| Windows | `yarn tauri build` | `.msi`, `.exe` | +| macOS | `yarn tauri build` | `.dmg`, `.app` | +| Linux | `yarn tauri build` | `.deb`, `.AppImage` | +| Android | `yarn tauri android build` | `.apk`, `.aab` | +| iOS | `yarn tauri ios build` | `.ipa` | diff --git a/.claude/rules/08-frontend-guide.md b/.claude/rules/08-frontend-guide.md index 15ba858b2..fb3eea29f 100644 --- a/.claude/rules/08-frontend-guide.md +++ b/.claude/rules/08-frontend-guide.md @@ -38,14 +38,24 @@ src/ │ ├── authSlice.ts # Authentication state │ ├── socketSlice.ts # Socket connection state │ ├── userSlice.ts # User profile state +│ ├── aiSlice.ts # AI system state +│ ├── skillsSlice.ts # Skills management state +│ ├── teamSlice.ts # Team collaboration 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 +├── lib/ # Core libraries +│ ├── ai/ # AI system architecture +│ │ ├── memory/ # Memory management with encryption +│ │ ├── constitution/ # AI behavior rules +│ │ ├── entities/ # Entity graph management +│ │ ├── sessions/ # Session capture and transcripts +│ │ └── providers/ # AI provider abstractions +│ └── 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 @@ -56,11 +66,18 @@ src/ │ ├── ProtectedRoute.tsx # Auth-gated routes │ ├── PublicRoute.tsx # Guest-only routes │ ├── ConnectionIndicator.tsx # Status indicators +│ ├── SkillsGrid.tsx # Skills catalog and management +│ ├── DownloadScreen.tsx # Multi-platform download system │ └── settings/ # Settings modal system │ ├── SettingsModal.tsx # Main container with routing │ ├── SettingsLayout.tsx # Modal wrapper with portal │ ├── SettingsHome.tsx # Main menu with profile -│ ├── panels/ConnectionsPanel.tsx # Connection management +│ ├── panels/ # Settings panels +│ │ ├── ConnectionsPanel.tsx # Connection management +│ │ ├── TeamPanel.tsx # Team management +│ │ ├── TeamMembersPanel.tsx # Member roles & permissions +│ │ ├── TeamInvitesPanel.tsx # Invitation system +│ │ └── BillingPanel.tsx # Premium features and billing │ ├── components/ # Menu items, header, back button │ └── hooks/ # Navigation and animation hooks └── utils/ # Utilities and config @@ -70,15 +87,31 @@ src/ ### Recent Architecture Changes -- **Settings Modal System**: Complete URL-based modal system with clean white design - - Modal routes: `/settings`, `/settings/connections` overlaying existing content - - Component structure: SettingsModal, SettingsLayout, ConnectionsPanel, hooks - - Redux integration: auth, user, telegram state for profile and connection management -- **HashRouter**: Switched from BrowserRouter for better desktop app compatibility -- **165+ TypeScript files**: Comprehensive component library with settings modal system -- **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 `alphahuman://` scheme +- **Code Quality Infrastructure**: ESLint, Prettier, and Husky hooks for automated quality checks + - Pre-commit/pre-push hooks with TypeScript compilation validation + - Type-only imports standardization and consolidated import statements + - GitHub workflow integration with quality gate checks +- **Advanced AI System**: Comprehensive artificial intelligence platform + - Memory management with encryption, chunking, and hybrid search capabilities + - Constitution-based AI behavior with GitHub integration for rule updates + - Entity graph migration to Neo4j backend for knowledge relationships + - Session capture, transcript management, and tool compression +- **Skills Management Platform**: Dynamic skill loading and management system + - SkillsGrid with setup status indicators and management controls + - GitHub sync integration for skills catalog updates + - Conditional rendering (setup wizard vs management panel) + - Skills submodule with background update synchronization +- **Team Collaboration Features**: Multi-user workspace management system + - TeamPanel, TeamMembersPanel, TeamInvitesPanel for comprehensive team management + - Role-based permissions and invitation system with Redux state management + - Team API integration with CRUD operations and member management +- **Enhanced Settings System**: Expanded modal system with multiple management panels + - Team management, billing, privacy, and advanced configuration panels + - Enhanced URL routing for deep-linking to specific settings sections + - Redux integration across auth, user, telegram, ai, skills, and team slices +- **200+ TypeScript files**: Comprehensive component and library ecosystem +- **Provider chain**: Redux → PersistGate → Socket → Telegram → AI → Skills → HashRouter → Routes +- **Enhanced CI/CD**: Python sidecar support, XGH_TOKEN authentication, GitHub Pages deployment ## React with Tauri diff --git a/CLAUDE.md b/CLAUDE.md index 4b3e18c8d..cbdcb16cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,7 +69,7 @@ cargo check --manifest-path src-tauri/Cargo.toml cargo clippy --manifest-path src-tauri/Cargo.toml ``` -No test framework is currently configured. No ESLint or Prettier configuration exists in the repo. +No test framework is currently configured. **ESLint and Prettier are configured** with Husky pre-commit/pre-push hooks for code quality enforcement. ## Architecture @@ -85,6 +85,9 @@ State lives in `src/store/` using Redux Toolkit slices: - **userSlice** — user profile - **socketSlice** — connection status, socket ID - **telegramSlice** — connection/auth status, chats, messages, threads (selectively persisted; loading/error states excluded) +- **aiSlice** — AI system state, memory management, session tracking +- **skillsSlice** — skills catalog, setup status, management state +- **teamSlice** — team management, member invites, permissions Redux Persist stores auth and telegram state (storage backend is configurable; default uses localStorage). The telegram slice has a complex nested structure in `src/store/telegram/` with separate files for types, reducers, extraReducers, and thunks. @@ -165,17 +168,43 @@ Key updates from recent commits: ### Major Additions -- **Settings Modal System** (`60054d8`): Complete URL-based settings modal with clean white design - - Modal infrastructure with backdrop blur and center positioning - - User profile integration with Redux state management - - Connection management panel reusing onboarding components - - URL routing for `/settings` and `/settings/connections` paths - - Mobile responsive design with accessibility features -- **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`) +- **ESLint & Prettier Integration** (`5896966`): Complete code quality toolchain + - ES module syntax for ESLint configuration with enhanced TypeScript support + - Husky pre-commit/pre-push hooks for automatic formatting and linting + - Type-only imports standardization across codebase + - Consolidated import statements and improved code organization + - GitHub workflows updated with Prettier and ESLint checks +- **Advanced Skills System** (`10ec1b3`): Comprehensive skill management platform + - Dynamic skills loading from local directory via Rust integration + - SkillSetupModal with conditional rendering (wizard vs management panel) + - Background GitHub sync for skills catalog updates + - Skills table with setup status indicators and management controls + - Enhanced skill metadata with setup hooks and descriptions +- **Team Management Features** (`10ec1b3`): Multi-user collaboration system + - TeamPanel, TeamMembersPanel, and TeamInvitesPanel components + - Redux state management for teams, members, and invites + - Team API integration with CRUD operations + - Settings modal routing for team management paths + - Role-based permissions and invitation system +- **AI System Enhancements**: Advanced memory and session management + - Hybrid search with encryption for AI memory + - Constitution-based AI behavior with GitHub integration + - Entity graph migration to Neo4j backend + - Session capture and transcript management + - Memory chunking and context formatting +- **Enhanced CI/CD Pipeline** (`b1d7bce`): Production-ready deployment + - XGH_TOKEN authentication for alphahumanxyz/alphahuman releases + - Python sidecar setup and caching for cross-platform builds + - Tauri configuration updates (com.alphahuman.app identifier) + - GitHub Pages deployment with optimized workflows + - Version tagging and environment variable management +- **Device Detection & Download System** (`9d74721`, `b5bccd2`): Enhanced multi-architecture download support + - Optimized asset parsing using Maps for unique architecture links per platform + - Enhanced DownloadScreen.tsx with architecture-specific download options + - Improved device detection for Windows, macOS, Linux, and Android platforms + - Added preference logic for more specific filenames in asset parsing + - Support for multiple architectures (x64, aarch64) with intelligent sorting +- **Version Bump**: Project updated to v0.20.0 (`891517c`) ### Design System Updates @@ -188,16 +217,36 @@ Key updates from recent commits: ### Component Structure -- **165+ TypeScript files** across `src/` directory (added settings modal system) -- **Settings Modal System**: Complete modal infrastructure in `src/components/settings/` +- **200+ TypeScript files** across `src/` directory with comprehensive tooling +- **AI System Architecture** (`src/lib/ai/`): Advanced artificial intelligence platform + - Memory management with encryption, chunking, and hybrid search + - Constitution-based behavior with GitHub integration + - Entity graph with Neo4j backend integration + - Session capture, transcript management, and tool compression + - Provider system with OpenAI integration and custom providers +- **Skills Management System**: Dynamic skill platform with Rust integration + - SkillsGrid.tsx - Skills catalog with setup status and management + - SkillSetupModal.tsx - Conditional wizard/management panel rendering + - SkillProvider.tsx - GitHub sync and local directory integration + - Skills submodule integration with background updates +- **Team Collaboration Features**: Multi-user workspace management + - TeamPanel.tsx - Team overview with member management + - TeamMembersPanel.tsx - Member roles and permissions + - TeamInvitesPanel.tsx - Invitation system with role assignment + - Team API integration with Redux state management +- **Settings Modal System**: Comprehensive configuration interface - SettingsModal.tsx - Main container with URL routing - SettingsLayout.tsx - Modal wrapper with createPortal - - SettingsHome.tsx - Main menu with profile and navigation - - ConnectionsPanel.tsx - Connection management with status indicators + - Enhanced panels: Billing, Team, Connections, Privacy, Profile - Hooks: useSettingsNavigation.ts, useSettingsAnimation.ts -- **Onboarding Flow**: Multi-step process with privacy, analytics, and connection steps -- **Authentication**: Web-to-desktop handoff using `alphahuman://` scheme -- **Connection Management**: Telegram MTProto and Socket.io integration +- **Download System**: Enhanced multi-platform distribution + - DownloadScreen.tsx - Platform detection with architecture support + - deviceDetection.ts - Comprehensive device/architecture utilities + - GitHub API integration for real-time release assets +- **Code Quality Infrastructure**: ESLint, Prettier, and Husky integration + - Pre-commit/pre-push hooks with TypeScript compilation checks + - Standardized type-only imports and consolidated statements + - GitHub workflow integration with automated quality checks ## Git Workflow @@ -205,10 +254,17 @@ Key updates from recent commits: ## Key Patterns +- **Code Quality**: ESLint and Prettier enforce code standards with Husky hooks. Use type-only imports (`import type`) and consolidate imports from same modules. - **No localStorage**: Avoid `localStorage` and `sessionStorage`; use Redux (and persist) for app state. Remove any direct usage when working on affected code. -- **Modal System**: Settings modal uses `createPortal` pattern with URL-based routing. Clean white design (not glass morphism) for system settings. Navigate with `/settings` and `/settings/connections` paths. +- **AI System Integration**: Use `src/lib/ai/` for memory management, constitution loading, entity queries, and session capture. AI providers abstracted through interface pattern. +- **Skills Management**: Skills loaded dynamically from local directory via Rust. Use `SkillProvider` for GitHub sync and `SkillsGrid` for management interface. +- **Team Collaboration**: Team features in `src/components/settings/panels/Team*`. Use Redux `teamSlice` for state management and `teamApi` for backend operations. +- **Device Detection**: Use `deviceDetection.ts` utilities for platform/architecture detection. Support multiple architectures per platform (x64, aarch64) with intelligent preference logic. +- **GitHub Integration**: Fetch release assets via GitHub API (`fetchLatestRelease()`) and parse by architecture (`parseReleaseAssetsByArchitecture()`). Use Maps for efficient unique architecture tracking. +- **Download System**: Platform-specific file type support (.exe/.msi for Windows, .dmg for macOS, .AppImage/.deb/.rpm for Linux, .apk for Android) with fallback links. +- **Modal System**: Settings modal uses `createPortal` pattern with URL-based routing. Clean white design (not glass morphism) for system settings. Navigate with `/settings` paths for different panels. - **Component Reuse**: Connection management reuses `connectOptions` array and components from onboarding flow. Maintains consistent UX patterns across features. -- **Redux Integration**: Settings modal integrates with existing slices - auth for logout, user for profile display, telegram for connection status. No new state management needed. +- **Redux Integration**: Multiple slices (auth, user, telegram, ai, skills, team) with Redux Persist. Use typed hooks and selectors. State functions accept optional `userId` param. - **Node polyfills**: Vite config (`vite.config.ts`) polyfills `buffer`, `process`, `util`, `os`, `crypto`, `stream` for the `telegram` package which requires Node APIs. - **Telegram IDs**: Use `big-integer` library, not native JS numbers (Telegram IDs exceed `Number.MAX_SAFE_INTEGER`). - **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`. @@ -216,8 +272,7 @@ Key updates from recent commits: - **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. - **Integration Libraries**: Each integration (Telegram, future Gmail, etc.) lives under `src/lib//` with its own `state/`, `services/`, `api/` subdirectories. Domain-specific services belong in the integration folder, not in `src/services/` (which holds only cross-cutting services like socketService, apiClient). -- **State Layer**: Each integration dispatches Redux changes through state functions in `src/lib//state/` — never import Redux actions directly from services or update handlers. State functions accept an optional `userId` param (falls back to `getCurrentUserId()`). -- **Unit Tests**: All unit tests live in `__tests__/` folders co-located with the code they test. +- **Unit Tests**: All unit tests live in `__tests__/` folders co-located with the code they test. Use Jest with TypeScript support. ## Platform Gotchas