Executive Summary
This document outlines the technical architecture of MALENIO, a privacy-focused Gmail extension that leverages local AI processing via Ollama. The architecture is designed with privacy as the primary concern, ensuring all email data remains on the user’s device while still providing advanced AI capabilities for email management.
Architecture Overview
MALENIO follows a client-side architecture pattern with five core components:
- Chrome Extension Framework: The container application implementing ManifestV3 requirements
- Gmail Interface Layer: Components that interact with the Gmail interface and API
- Local AI Processing Engine: Integration with Ollama for on-device AI inference
- Data Management System: Secure local storage and data handling
- User Interface Components: Gmail-native UI elements for seamless integration
- Management Platform: Web application for account, subscription, and advanced configuration management
Note: The above diagram is a placeholder and should be replaced with an actual architecture diagram.
Component Architecture
1. Chrome Extension Framework
The extension follows Chrome’s ManifestV3 architecture with the following components:
1.1 Background Service Worker
- Purpose: Long-lived event handler serving as application controller
- Responsibilities:
- Manage extension lifecycle events
- Coordinate communication between components
- Handle authentication and permissions
- Manage Ollama connection state
- Orchestrate background processing tasks
1.2 Content Scripts
- Purpose: Scripts injected into Gmail web pages
- Responsibilities:
- Access and modify Gmail DOM
- Capture user interactions
- Inject UI components
- Apply visual changes to Gmail interface
- Interact with email content
1.3 Popup Interface
- Purpose: User configuration and controls
- Responsibilities:
- Provide extension settings
- Display processing status
- Offer manual controls
- Show privacy guarantees
- Configure AI model behavior
1.4 Extension Storage
- Purpose: Persistent state management
- Responsibilities:
- Store user preferences
- Maintain extension state
- Cache frequently used data
- Store model parameters
2. Gmail Interface Layer
This layer handles all interactions with Gmail and email data:
2.1 Gmail API Client
- Purpose: Provide programmatic access to Gmail data
- Responsibilities:
- Authenticate with Gmail
- Retrieve email content
- Apply labels and organization
- Implement search functionality
- Manage email metadata
2.2 DOM Integration Module
- Purpose: Direct integration with Gmail interface
- Responsibilities:
- Insert custom UI elements
- Capture user actions
- Modify Gmail rendering
- Implement keyboard shortcuts
- Ensure compatibility with Gmail updates
2.3 Email Parser
- Purpose: Extract structured data from emails
- Responsibilities:
- Parse email content and structure
- Extract metadata (sender, recipients, dates, etc.)
- Identify conversation threads
- Extract key entities and topics
- Prepare data for AI processing
2.4 Advanced Gmail API Integration
- Purpose: Leverage Gmail API capabilities for powerful search and batch operations
- Responsibilities:
- Advanced search operations:
- Utilize Gmail’s search syntax for sophisticated queries (from:, to:, subject:, etc.)
- Implement semantic search extensions on top of Gmail’s native search
- Support complex multi-criteria queries with natural language parsing
- Cache and optimize frequent search patterns for performance
- Batch operations management:
- Implement multi-message label operations through
users.messages.batchModify
- Support batch operations on up to 1000 messages per request
- Implement archiving and moving to trash through label manipulation (INBOX, TRASH)
- Handle error recovery and retries for batch operations
- Ensure transactional integrity for batch edits with rollback capability
- Process large result sets with pagination and progressive handling
- Implement multi-message label operations through
- System label orchestration:
- Manage system labels (INBOX, TRASH, SPAM, UNREAD, etc.) for state changes
- Implement move-to-trash operations by removing INBOX and adding TRASH labels
- Support archiving by removing the INBOX label from messages
- Handle status changes (read/unread) through label management
- Maintain synchronization between UI state and actual label states
- Custom label management:
- Create, update, and delete user-defined labels
- Maintain optimal label taxonomy based on user instructions
- Implement efficient label application to message groups
- Support hierarchical label structures (nested labels)
- Advanced search operations:
3. Local AI Processing Engine
This is the core intelligence component, providing AI capabilities without cloud dependencies:
3.1 Ollama Integration
- Purpose: Connect to local Ollama instance
- Responsibilities:
- Establish WebSocket connection to Ollama
- Send inference requests
- Process model responses
- Manage model selection
- Handle connection errors gracefully
3.2 Model Manager
- Purpose: Handle AI model operations
- Responsibilities:
- Dynamic model discovery:
- Real-time querying of available models from Ollama repository
- Regular checks for newly available models
- Metadata retrieval for model capabilities and requirements
- Filtering based on device compatibility
- On-demand model switching:
- Ability to change models at any time through the settings interface
- Background downloading of new models while continuing to use current model
- Seamless transition between models once download is complete
- Model comparison tools to help users select the most appropriate option
- Model registry management:
- Local caching of multiple downloaded models
- Intelligent cleanup of unused models to save disk space
- Version tracking across model updates
- Select appropriate models for specific tasks
- Optimize inference performance
- Manage model parameters
- Track model performance metrics
- Handle model updates
- Dynamic model discovery:
3.3 Inference Processor
- Purpose: Process AI inferences for email tasks
- Responsibilities:
- Convert emails to model inputs
- Process model outputs
- Apply tag recommendations
- Extract semantic understanding
- Identify patterns across emails
- Analyze sentiment and emotional tone
- Track mood patterns over time
- Detect tone shifts in communications
- Generate personalized response suggestions
- Adapt to user’s communication style
- Parse natural language tagging instructions
- Convert user instructions to executable rules
- Apply user-defined categorization criteria
3.4 Learning Module
- Purpose: Adapt to user behavior
- Responsibilities:
- Track user interactions and preferences
- Build personalized models
- Refine tagging suggestions
- Adapt to evolving email patterns
- Integrate user feedback
- Model user writing style and strategies
- Identify successful communication patterns
- Learn context-specific communication approaches
- Maintain multi-level communication profiles:
- General user writing style across all communications
- Recipient-specific communication patterns
- Thread-specific conversation dynamics
- Temporal adaptations to evolving communication style
- Prioritize conversation-specific patterns when available
- Apply general patterns as fallback for new or limited conversations
- Cross-learn between specific and general communication models
- Detect and preserve successful communication strategies
4. Data Management System
This component ensures secure handling of all data:
4.1 Local Storage Manager
- Purpose: Secure data persistence
- Responsibilities:
- Encrypt sensitive data
- Implement secure storage patterns
- Manage storage quotas
- Handle data versioning
- Implement backup/recovery
4.2 Privacy Control System
- Purpose: Enforce privacy guarantees
- Responsibilities:
- Implement privacy settings
- Enforce data handling policies
- Block unauthorized data transmission
- Provide transparency controls
- Support data minimization
4.3 Analytics Engine
- Purpose: Privacy-preserving metrics
- Responsibilities:
- Collect anonymous usage statistics
- Implement differential privacy techniques
- Support local-only analytics
- Provide performance insights
- Generate debug information
5. User Interface Components
These components create a seamless user experience:
5.1 Tag Management UI
- Purpose: Interface for email tagging
- Responsibilities:
- Display tag suggestions
- Provide tag management
- Show confidence levels
- Support tag customization
- Handle tag applications
- Accept natural language tagging instructions
- Display interpretation of user instructions
- Show rule execution metrics and results
- Allow refinement of instructions
- Provide conversational interface for organizational commands
5.2 Pattern Visualization
- Purpose: Display communication insights
- Responsibilities:
- Visualize email patterns
- Show relationship graphs
- Present time-based analyses
- Display topic clusters
- Integrate with Gmail views
- Render emotional tone trends
- Visualize mood analytics by period
- Provide sentiment comparison across contacts
5.3 Search Enhancement
- Purpose: Upgrade Gmail search
- Responsibilities:
- Implement semantic search
- Provide advanced query capabilities
- Surface related communications
- Support natural language queries
- Integrate with Gmail search
- Enable emotional tone-based searching
5.4 Response Assistant Interface
- Purpose: Support personalized email replies
- Responsibilities:
- Present contextually relevant reply suggestions
- Offer multiple response options with varying tones
- Display confidence indicators for suggestions
- Provide editing interface for reply refinement
- Integrate seamlessly with Gmail compose interface
- Show strategy and tone indicators for suggestions
- Allow style preference adjustments
5.5 Model Management Interface
- Purpose: Enable dynamic model discovery and switching
- Responsibilities:
- Display real-time list of available models from Ollama repository
- Show detailed model information (size, capabilities, hardware requirements)
- Provide comparative performance metrics between models
- Enable one-click model switching with progress indicators
- Display currently active model and its status
- Show hardware compatibility assessment for each model
- Allow scheduling of model updates during off-hours
- Provide usage statistics by model
- Enable model-specific configuration and tuning
5.6 Advanced Search and Batch Action Interface
- Purpose: Provide powerful search capabilities with batch action functionality
- Responsibilities:
- Present natural language search input with suggestions
- Offer structured search builder alternative with field-specific filters
- Display search results with rich metadata preview
- Support results filtering and refinement
- Provide batch action toolbar for common operations:
- Multi-select mechanism for email selection
- Bulk tagging/labeling controls
- Mass archiving with confirmation
- Group prioritization tools
- Batch response generation interface
- Show operation progress for long-running batch tasks
- Present result visualizations and pattern analytics
- Save and manage search templates
- Provide undo/redo capability for batch operations
- Display operation history and audit trail
6. Management Platform
This web-based platform handles all administrative and commercial aspects of the service:
6.1 User Account System
- Purpose: Manage user identities and access
- Responsibilities:
- User registration and authentication
- Profile management
- Security settings
- Account status monitoring
- User preferences synchronization
- Multi-device identity management
6.2 Subscription Management
- Purpose: Handle commercial aspects of the service
- Responsibilities:
- Plan selection and management
- Payment processing integration
- Billing and invoicing
- Subscription lifecycle management
- Upgrade/downgrade handling
- Trial conversion optimization
- Payment provider integrations
6.3 Advanced Configuration Portal
- Purpose: Provide extended configuration capabilities
- Responsibilities:
- Cross-device settings synchronization
- Complex preference management
- Model selection and tuning
- Advanced rule configuration
- Backup and restore functionality
- Usage quota management
6.4 Analytics Dashboard
- Purpose: Provide insights into personal usage
- Responsibilities:
- Privacy-preserving usage statistics
- Productivity metrics visualization
- Feature utilization insights
- Time-saving analytics
- Pattern discovery visualization
- Personal ROI calculation
6.5 Support System
- Purpose: Provide user assistance
- Responsibilities:
- Knowledge base management
- Ticket creation and tracking
- Community forum management
- Feature request collection
- Onboarding assistance
- Tutorial and guide delivery
Data Flow Architecture
MALENIO’s data flow is designed to ensure all processing remains local:
1. Email Processing Flow
- Gmail event triggers extension activation
- Email content is securely accessed locally
- Local AI model processes content for analysis
- Advanced metadata generation:
- Content categorization
- Sentiment analysis
- Entity and topic extraction
- Relationship mapping
- Priority assessment
- Action item identification
- Secure local indexing for advanced retrieval:
- Vector embeddings for semantic search
- Structured metadata for filtered queries
- Relationship graphs for contextual understanding
- Multi-dimensional indices for complex query support
- Batch operation capabilities:
- Query engine for complex criteria matching
- Result set management with pagination
- Transaction handling for group operations
- Rollback capability for error recovery
- Performance optimization for large batches
- UI updates to reflect processed information
- User initiates search with natural language or structured queries
- System retrieves matching emails using local indices
- User performs batch actions on result set
- Actions are executed with progress tracking
- Results are stored and synchronized with Gmail
2. AI Processing Flow
- Structured email data sent to Ollama via localhost connection
- Ollama processes data with selected model
- Inference results returned to extension
- Results processed into actionable outputs
- Original email data and inferences remain local
3. User Interaction Flow
- UI displays AI-generated suggestions
- User interacts with tags and organization
- User feedback captured for adaptation
- Interactions stored in learning module
- Gmail interface updated to reflect changes
4. Response Generation Flow
- User views or selects an email requiring response
- Context analyzer aggregates thread history and metadata for the specific conversation
- System determines if sufficient conversation-specific history exists
- If sufficient history exists: a. Communication style analyzer retrieves user’s patterns specific to this recipient and thread b. Thread-specific tone and strategy patterns are prioritized
- If limited specific history: a. System analyzes user’s general communication patterns across all emails b. Generic writing style, tone preferences, and response strategies are extracted c. These general patterns are adapted to match what is known about the specific recipient
- Ollama generates multiple response options matching appropriate style/tone: a. Primary options based on thread-specific history (if available) b. Alternative options based on general communication patterns c. Options with varying levels of formality and tone appropriate to the relationship
- User selects, edits, or refines suggested response
- Learning module captures user modifications for improvement: a. Specific adaptations to this thread are prioritized for future exchanges with this recipient b. General writing preferences are updated in the user’s communication profile
5. Instruction-Based Tagging Flow
- User provides natural language instruction for email organization
- Instruction parser extracts intent, criteria, and target labels
- System converts instruction to semantic matching rules
- Rules are applied to relevant emails in inbox
- Matching emails are tagged according to instruction
- System displays confirmation and statistics on applied changes
- User feedback is captured to refine instruction understanding
- Instruction and its interpretation are stored for future application
6. Account Management Flow
- User accesses web management platform via secure connection
- Authentication system validates identity and permissions
- Account management actions are performed (subscription changes, configuration updates)
- Changes are synchronized to extension via secure API
- Extension receives updates during next activation
- Local confirmation of changes is displayed to user
7. Model Discovery and Switching Flow
- System periodically queries Ollama repository for available models
- New and updated models are identified and metadata retrieved
- Models are analyzed for compatibility with user’s hardware
- User accesses model management interface via extension settings
- System displays available models with comparative information:
- Model capabilities and specializations
- Hardware requirements and performance expectations
- Download size and disk space requirements
- Community ratings and suggested use cases
- User selects new model to download or switch to
- If model is not downloaded previously:
- Background download begins with progress tracking
- Current model remains active during download
- Notification appears when download completes
- User confirms model switch when ready
- System performs seamless transition to new model:
- Warm-up inference tasks to prime the model
- Configuration adjustment based on model requirements
- Performance baseline establishment
- User receives confirmation of successful model switch
- System continues to monitor model performance and suggests optimizations
8. Account Management Flow
- User accesses web management platform via secure connection
- Authentication system validates identity and permissions
- Account management actions are performed (subscription changes, configuration updates)
- Changes are synchronized to extension via secure API
- Extension receives updates during next activation
- Local confirmation of changes is displayed to user
Note: The above diagram is a placeholder and should be replaced with an actual data flow diagram.
Security Architecture
Security is a foundational aspect of MALENIO’s architecture:
1. Privacy Protection Measures
- All email processing occurs locally on user device
- No transmission of email content to external services
- Encrypted local storage for sensitive information
- Connection to Ollama restricted to localhost
- Clear user visibility into all data handling
2. Data Storage Security
- Extension storage encrypted using browser-provided mechanisms
- Sensitive data never persisted in plain text
- Minimal data retention policy
- Storage access limited to extension context
- Regular purging of unnecessary data
3. Authentication & Authorization
- Standard OAuth for Gmail API access
- Minimal permission scope requests
- Clear permission explanations to users
- Secure token handling
- Regular credential rotation
4. Secure Development Practices
- Regular security audits
- Static code analysis
- Dependency vulnerability scanning
- Security-focused code reviews
- Comprehensive logging and monitoring
Technical Dependencies
MALENIO relies on the following key technologies:
1. Frontend Technologies
- JavaScript/TypeScript: Core programming language
- HTML/CSS: UI rendering
- React: Component-based UI framework
- D3.js: Data visualization
- WebAssembly: Performance-critical operations
2. AI & Processing
- Ollama: Local model inference engine
- Multiple model options:
- DeepSeek-R1-Distill-Qwen-1.5B: Lightweight version (1.1GB size, requires ~6GB VRAM) - ideal for systems with limited resources
- DeepSeek-R1-Distill-Qwen-7B: Balanced option with improved capabilities (requires ~12GB VRAM)
- DeepSeek-R1-Distill-Llama-8B: Llama-based alternative with strong reasoning (requires ~14GB VRAM)
- Llama 3.1 (8B): High-quality alternative with excellent performance (requires ~16GB VRAM)
- TensorFlow.js: In-browser machine learning
- Web Workers: Parallel processing
- IndexedDB: Structured data storage
3. Browser APIs
- Chrome Extension API: Extension framework
- Storage API: Persistent storage
- WebSocket API: Ollama communication
- Fetch API: Network requests
- Service Worker API: Background processing
4. Third-Party Services
- Gmail API: Email interaction
- Google OAuth: Authentication
- Chrome Web Store: Distribution
5. Web Platform Technologies
- Node.js: Server-side JavaScript runtime
- React: Frontend framework for management portal
- PostgreSQL: Relational database for user accounts
- Stripe/PayPal: Payment processing integration
- Redis: Session and cache management
- AWS/GCP: Cloud infrastructure hosting
Performance Considerations
MALENIO’s architecture addresses performance challenges of local AI:
1. Processing Optimization
- Asynchronous background processing
- Batch processing for multiple emails
- Progressive enhancement based on available resources
- Prioritization of visible and recent emails
- Caching of inference results
- Model distillation techniques for efficiency
- Quantized model operations for performance
2. Resource Management
- Throttling during high browser load
- Adaptive model selection based on device capabilities
- Intelligent scheduling of processing tasks
- Memory-efficient data structures
- Graceful degradation on low-resource systems
3. User Experience Impact
- Non-blocking UI operations
- Progress indicators for long-running tasks
- Immediate feedback for user actions
- Deferred processing of non-critical tasks
- Performance monitoring and adaptation
Deployment Architecture
MALENIO follows a standard Chrome extension deployment approach:
1. Distribution
- Chrome Web Store as primary distribution channel
- Self-hosting option for enterprise deployments
- Continuous delivery pipeline
- Staged rollout capability
- Version management
2. Updates & Maintenance
- Automatic extension updates via Chrome
- Model updates through Ollama
- Remote configuration updates
- Performance telemetry collection
- Bug reporting mechanism
3. Environment Support
- Chrome browser for desktop (Windows, macOS, Linux)
- Minimum Chrome version 89+
- Ollama availability on user system
- Minimum hardware requirements defined
- Network connectivity for initial setup
4. Web Platform Deployment
- Containerized microservices architecture
- Multi-region cloud deployment
- Database replication and high availability
- CDN for static assets
- API gateway for service orchestration
- CI/CD pipeline for automated deployment
Technical Risks & Mitigations
Key technical risks and mitigation strategies:
Risk | Impact | Mitigation |
---|---|---|
Ollama connection failures | Loss of AI capabilities | Graceful degradation to basic functionality; clear error messages; automatic reconnection |
Gmail DOM changes | UI integration breakage | Component-based design; automated testing; rapid update pipeline; feature flags |
Browser resource constraints | Poor performance | Adaptive processing; background operations; resource monitoring; performance throttling |
Extension permission changes | Functional limitations | Minimal permission design; feature modularity; fallback capabilities |
Local model limitations | Reduced AI quality | Model optimization; task-specific models; continuous model improvements |
Hardware incompatibility with selected model | Performance issues or inability to run preferred model | Multi-tier model options; clear hardware requirements; automatic fallback to compatible models; graceful degradation path |
Installation and Setup Architecture
MALENIO requires a local AI environment while maintaining minimal friction for users. Our solution:
1. All-in-One Installer
- Purpose: Provide frictionless setup experience
- Components:
- Unified installer package for Windows, macOS, and Linux
- System requirements checker
- Ollama bundled installation (no separate download)
- Base model downloader and configurator
- Chrome extension auto-installer
- Visual setup wizard
2. Installation Process Flow
- One-Click Start:
- User downloads the MALENIO installer from the official website
- Installer launches with visual wizard interface
- Automated System Check:
- Hardware compatibility verification (RAM, disk space, CPU/GPU)
- Existing components detection (Ollama if already installed)
- Platform-specific optimizations identification
- Guided Installation:
- Single confirmation to install all components
- Progress visualization with clear stages
- Background download and installation of Ollama
- Dynamic model ecosystem:
- Initial model recommendation based on hardware detection
- Access to complete Ollama model library at installation and post-installation
- Real-time model repository updates for latest available options
- Initial selection from popular models with clear capabilities comparison:
- Lightweight options optimized for basic hardware
- Balanced models for standard systems
- High-performance options for advanced hardware
- Clear hardware requirements displayed for each model
- Ability to change models anytime after installation
- Background download system with progress indicators and pause/resume capability
- Chrome extension installation directly from installer
- Configuration Automation:
- Automatic Ollama configuration
- Local port setup and security configuration
- Initial model loading and verification
- Extension-to-Ollama connection establishment
- Test verification of full pipeline
- User Onboarding:
- Immediate in-browser tutorial after installation
- Gmail integration demonstration
- Quick-start guide with common commands
- Success confirmation with next steps
3. Platform-Specific Optimizations
Windows
- Native installer (.exe) with admin privilege handling
- Windows-optimized Ollama build
- Start menu and desktop shortcut creation
- Windows Defender exceptions for performance
macOS
- Native .pkg installer with Apple notarization
- Apple Silicon optimization for M1/M2/M3 chips
- Automatic Gatekeeper handling
- Installation in Applications folder with permissions
Linux
- AppImage and native package formats (.deb, .rpm)
- Repository configuration for updates
- Dependency resolution automation
- Hardware acceleration detection and configuration
4. Update and Maintenance
- Silent background updates for Ollama
- Incremental model updates to minimize bandwidth
- Health monitoring and automatic repairs
- Configuration backup and restore
- Extension-to-local synchronization system
5. Friction Minimization Techniques
- Total clicks from download to functioning: <5
- Installation time target: <3 minutes on average systems
- Zero command-line interactions required
- Intelligent defaults requiring minimal user decisions
- Progressive disclosure of advanced options
- Visual feedback at all stages of installation
- Automatic recovery from common installation errors
Future Architecture Considerations
Areas for architectural evolution:
1. Multi-Platform Support
- Extension architecture for Firefox and Edge
- Shared core components across platforms
- Platform-specific adaptation layers
- Consistent experience across browsers
2. Mobile Strategy
- Potential companion mobile application
- Shared ML models between desktop and mobile
- Synchronization architecture
- Mobile-specific UI optimizations
3. Advanced AI Capabilities
- Model Strategy Evolution:
- Regular addition of new optimized models as they become available
- User-configurable default model preferences
- Automatic model switching based on task complexity and resource availability
- Performance benchmarking and recommendations
- Multi-model orchestration:
- Task-specific model selection for optimal performance
- Ensemble approaches combining multiple models for improved accuracy
- Memory-efficient model swapping techniques
- Fine-tuning infrastructure:
- User-specific adaptation of models based on communication patterns
- Privacy-preserving on-device fine-tuning
- Continuous learning from user interactions
- Knowledge graph integrations
- Cross-email semantic understanding
References
- See 04_product_definition.md for product requirements
- Google. (2024). Chrome Extensions Development Guide. Chrome Developer Documentation. https://developer.chrome.com/docs/extensions/
- Google. (2024). Gmail API Reference. Google API Documentation. https://developers.google.com/gmail/api/reference/rest
- Ollama Documentation. (2024). API Reference. https://ollama.com/docs/api
- Meta AI. (2024). Llama 3.2 Model Card. https://ai.meta.com/llama/
- Meta AI. (2024). Knowledge Distillation for LLM Efficiency. Meta AI Research.
- Chrome Extension Manifest V3. (2023). Chrome Developers. https://developer.chrome.com/docs/extensions/mv3/intro/
- Russinovich, M. (2023). Securing Browser Extensions. Microsoft Research. https://www.microsoft.com/en-us/research/publication/securing-browser-extensions/
- WebAssembly Working Group. (2024). WebAssembly Specification. https://webassembly.github.io/spec/
- React Documentation. (2024). React for Web Applications. https://react.dev/
- Stripe. (2024). Payment Integration API Documentation. https://stripe.com/docs/api