admin/openhuman
1
0
Fork 0
mirror of https://github.com/tinyhumansai/openhuman.git synced 2026-07-30 06:32:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update CLAUDE.md with new features, state slices, and code quality tools

Browse Source 
- 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
This commit is contained in:
cyrus
2026-02-02 16:39:56 +05:30
parent e3f46680ec
commit f2704e44cd
4 changed files with 209 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/rules/01-project-overview.md
+38 -10
View File
@@ -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
.claude/rules/02-development-commands.md
+47 -25
View File
@@ -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 <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` |
.claude/rules/08-frontend-guide.md
+46 -13
View File
@@ -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
CLAUDE.md
+78 -23
View File
@@ -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/<integration>/` 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/<integration>/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