Arumbu

AI-driven career guidance mobile application with an interactive animated mascot.

Overview

Arumbu is a React Native mobile app built with Expo that provides AI-driven career guidance through an interactive mascot. The mascot features four animated states (idle, listening, thinking, speaking) and delivers a conversational interface for career advice, skill gap analysis, and personalized learning paths.

Features

Features

User Experience

• Interactive Mascot: Full-body animated character figure with four distinct states
  • 2D & 3D Support: Toggle between 2D React Native animations and 3D Lottie animations
  • Idle: Gentle breathing with subtle arm sway (2s cycle)
  • Listening: Pulsing green body with arms raised, attentive pose (500ms cycle)
  • Thinking: Head tilting side-to-side with thinking bubbles, hand-to-head gesture (1-2s cycle)
  • Speaking: Head bobbing with alternating arm gestures (400ms cycle)
  • Customizable: Easy to add your own 3D mascot designs (see MASCOT_3D_GUIDE.md)
• Voice Interaction UI: Recording controls with visual feedback (backend integration pending)
• Conversation History: Chat-style interface with user/mascot messages and timestamps
• Modern UI Design: Clean interface with purple/pink color scheme, smooth animations at 60fps
• Cross-Platform: Runs on iOS, Android, and Web via Expo

Phase 1 Features ✅

• User Authentication: Login/Signup with language selection
• Multi-Language Support: Structure for 10 Indian languages (English, Hindi, Tamil, Telugu, Bengali, Marathi, Kannada, Malayalam, Gujarati, Punjabi)
• Career Roadmap: Personalized career path visualization with milestones
• Service Architecture: Modular services for AI, translation, conversation management
• Type-Safe: Complete TypeScript type definitions for all data models

Phase 2 Features (In Progress) ✅ Core Complete

• Session Persistence: User sessions persist across app restarts using AsyncStorage
• Voice Recording: Real audio recording with Expo AV and microphone permission handling
• Conversation Persistence: Conversation history saved locally with AsyncStorage
• Error Handling: Error boundary component for graceful error recovery
• Environment Configuration: Secure configuration structure for API keys and feature flags
• 3D Mascot Support: Lottie-based 3D mascot system with easy customization
• Ready for Integration: Services structured for easy API integration (OpenAI, Google Translate, Speech-to-Text)

Tech Stack

• React Native: 0.81.5
• Expo: ~54.0.0
• React: 19.1.0
• TypeScript: ~5.8.0
• React Navigation: Stack navigator for screen management
• Context API: State management for authentication
• Animations: React Native Animated API + Lottie for 2D/3D mascot animations
• AsyncStorage: Local data persistence for sessions and conversations
• Expo AV: Audio recording and playback functionality

Project Structure

Arumbu/
├── src/
│   ├── components/
│   │   ├── Mascot.tsx              # Animated mascot (243 lines)
│   │   ├── InteractionControls.tsx # Recording controls (155 lines)
│   │   ├── ConversationDisplay.tsx # Chat interface (130 lines)
│   │   └── ErrorBoundary.tsx       # Error handling component
│   ├── contexts/
│   │   └── AuthContext.tsx         # Authentication state management
│   ├── screens/
│   │   ├── HomeScreen.tsx          # Welcome screen
│   │   ├── InteractionScreen.tsx   # Main conversation interface with voice recording
│   │   ├── LoginScreen.tsx         # User login
│   │   ├── SignupScreen.tsx        # User registration
│   │   └── RoadmapScreen.tsx       # Career roadmap visualization
│   ├── services/
│   │   ├── aiService.ts            # AI reasoning and recommendations
│   │   ├── authService.ts          # User authentication with AsyncStorage
│   │   ├── conversationService.ts  # Message handling with persistence
│   │   ├── roadmapService.ts       # Career path generation
│   │   └── translationService.ts   # Multi-language support
│   ├── types/
│   │   ├── mascot.ts               # Mascot state definitions
│   │   ├── user.ts                 # User and profile types
│   │   ├── conversation.ts         # Message and conversation types
│   │   └── career.ts               # Career, skill, and roadmap types
│   ├── config/
│   │   └── environment.ts          # Environment configuration and API keys
│   ├── constants/
│   │   └── theme.ts                # Design tokens
│   └── App.tsx                     # Root component with navigation
├── __tests__/                      # Test files
├── assets/                         # Images and resources
├── app.json                        # Expo configuration
├── package.json                    # Dependencies
├── tsconfig.json                   # TypeScript config
└── README.md                       # This file

How It Works

Mascot States & Animations

Each mascot state has a unique animation, color, and body language:

• IDLE (Purple): Gentle breathing with subtle arm movement, relaxed standing pose
• LISTENING (Green): Pulsing body with arms slightly raised, attentive and engaged
• THINKING (Orange): Head tilting with thinking bubbles, hand-to-head contemplative gesture
• SPEAKING (Blue): Head bobbing with expressive arm gestures, animated conversation

Interaction Flow

1. User taps "Start Recording" button
2. Mascot enters LISTENING state (green, pulsing with raised arms)
3. User speaks, then taps "Stop Recording"
4. Mascot enters THINKING state (orange, head tilting with thinking bubbles)
5. Mascot enters SPEAKING state (blue, head bobbing with arm gestures)
6. Response appears in conversation history
7. Mascot returns to IDLE state (gentle breathing)

Note: Currently uses simulated responses. Backend integration needed for real AI.

Installation & Setup

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Expo Go app on your mobile device (optional)

Quick Start

1. Clone the repository:

git clone https://github.com/codervaruns/Arumbu.git
cd Arumbu

2. Install dependencies:

npm install

3. Start the development server:

npm start

4. Run on your preferred platform:
   • Press a for Android emulator
   • Press i for iOS simulator (Mac only)
   • Press w for web browser
   • Scan QR code with Expo Go app on your phone

Available Commands

npm start          # Start Expo dev server
npm run android    # Run on Android
npm run ios        # Run on iOS (Mac only)
npm run web        # Run in web browser
npm test           # Run tests
npm run lint       # Lint code

Development

Code Organization

• Components: Reusable UI elements (Mascot, Controls, Conversation)
• Screens: Full-page views (Home, Interaction)
• Types: TypeScript interfaces and enums
• Constants: Theme tokens (colors, spacing, typography)
• Config: Application configuration (mascot settings, environment)

3D Mascot Customization

The app now supports custom 3D mascot designs using Lottie animations!

Quick Start:

1. Set use3D: true in src/config/mascot.ts (already enabled)
2. Add your Lottie animation files to assets/animations/
3. Update the file paths in the config

For detailed instructions, see MASCOT_3D_GUIDE.md

Switch back to 2D: Set use3D: false in src/config/mascot.ts

Design System

// Colors
Primary: #6C63FF (Purple)
Secondary: #FF6584 (Pink)
Listening: #48BB78 (Green)
Thinking: #F6AD55 (Orange)
Speaking: #4299E1 (Blue)

// Spacing: xs=4, sm=8, md=16, lg=24, xl=32, xxl=48
// Font Sizes: xs=12, sm=14, md=16, lg=20, xl=24, xxl=32

Roadmap

Phase 1: UI/UX & Core Structure ✅ Complete

• Interactive mascot with 4 states
• Conversation interface
• Recording controls
• Smooth animations
• Authentication system (Login/Signup)
• Service layer architecture (AI, Translation, Conversation, Roadmap)
• Type definitions for User, Career, and Conversation data
• Roadmap visualization screen

Phase 2: Backend Integration (In Progress) ✅ Core Features Complete

• ✅ Session Persistence - AsyncStorage integration for user authentication
• ✅ Voice Recording - Expo AV integration with microphone permissions
• ✅ Conversation Persistence - AsyncStorage integration for conversation history
• ✅ Error Handling - Error boundary component for graceful error recovery
• ✅ Environment Configuration - Structured config for API keys and feature flags
• 🔄 Voice recording & speech-to-text API integration (structure ready)
• 🔄 Real AI service integration for career guidance (structure ready)
• 🔄 Real translation API integration (structure ready)

Phase 3: Advanced Features (Planned)

• Real-time skill gap analysis with ML
• Interactive career roadmap with progress tracking
• Personalized learning path recommendations
• Local opportunity matching
• Gamification and achievement system

Architecture

The application follows a modular architecture:

src/
├── components/          # Reusable UI components
├── contexts/           # React context providers (Auth)
├── screens/            # Full-page views
├── services/           # Business logic and API interfaces
│   ├── aiService.ts           # AI reasoning and recommendations
│   ├── authService.ts         # User authentication
│   ├── conversationService.ts # Message handling
│   ├── roadmapService.ts      # Career path generation
│   └── translationService.ts  # Multi-language support
├── types/              # TypeScript type definitions
└── constants/          # Theme and configuration

Service Layer (Ready for Integration)

All services are structured with clear interfaces and are ready to integrate with:

• AI/ML APIs: OpenAI, Anthropic, or custom models
• Translation APIs: Google Translate, Azure Translator
• Database: Firebase, Supabase, or custom backend
• Voice Recognition: Speech-to-text services

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT

---

Status: Phase 2 In Progress - Core Backend Integration Complete ✅
Features: Session Persistence, Voice Recording, Conversation Persistence, Error Handling
Last Updated: January 3, 2026