Your comprehensive guide to understanding, using, and contributing to Calm Attack
Welcome to the complete documentation for Calm Attack - the open-source Flutter app designed to help people manage panic attacks through scientifically-backed grounding techniques.
- 📖 About This Documentation
- 🎯 Project Overview
- 🏗️ Architecture
- ✨ Features Deep Dive
- 🛠️ Development
- 🎨 Design Guidelines
- 🔒 Privacy & Security
- 📱 Platform Specifics
- 🤝 Community
- 📚 Resources
This documentation is designed for:
- 👩💻 Developers wanting to contribute
- 🎨 Designers improving user experience
- 🧠 Mental Health Professionals providing feedback
- 👥 Community Members understanding the project
- 📱 Users wanting to understand features
To provide immediate, accessible, and effective panic attack relief through technology, while maintaining complete user privacy and leveraging community-driven development.
- 🔒 Privacy First: No data collection, completely offline
- ♿ Accessibility: Usable by everyone, including those with disabilities
- 🧠 Science-Based: Grounded in proven mental health techniques
- 👥 Community-Driven: Built by people who understand the struggle
- 💝 Free Forever: Open source ensures accessibility
- People experiencing panic attacks
- Individuals with anxiety disorders
- Mental health support networks
- Healthcare professionals
- Wellness advocates
- Framework: Flutter 3.0+
- Language: Dart
- Audio: AudioPlayers package
- Animations: Rive animations
- Haptics: Vibration package
- State Management: StatefulWidget pattern
Calm-Attack/
├── lib/ # Main application code
│ ├── main.dart # App entry point with theming
│ ├── Pages/ # Screen widgets
│ │ ├── start_screen.dart
│ │ ├── breathing_screen.dart
│ │ ├── audio_screen.dart
│ │ ├── vibration_screen.dart
│ │ ├── taste_screen.dart
│ │ ├── smell_screen.dart
│ │ ├── bubble_pop_game_screen.dart
│ │ └── finish_screen.dart
│ ├── core/ # Core architecture (NEW!)
│ │ ├── constants/ # App-wide constants
│ │ │ └── app_constants.dart
│ │ ├── utils/ # Utility functions
│ │ │ ├── audio_utils.dart
│ │ │ ├── navigation_utils.dart
│ │ │ └── session_utils.dart
│ │ └── widgets/ # Reusable UI components
│ │ └── common_widgets.dart
│ ├── Animations/ # Custom animations
│ └── Buttons/ # Legacy UI components
├── assets/ # Static assets
│ ├── *.png # Images and icons
│ ├── *.mp3 # Audio files (music and pop sounds)
│ ├── *.riv # Rive animations
│ ├── Smell/ # Smell exercise images
│ └── Taste/ # Taste exercise images
├── android/ # Android-specific code
├── ios/ # iOS-specific code
└── docs/ # Documentation files
- Start Screen → Get Started button
- Breathing Screen → 3-3-3 breathing exercise
- Audio Screen → Nature sounds and music
- Vibration Screen → Haptic feedback exercise
- Taste Screen → Visual taste imagination
- Smell Screen → Visual scent imagination
- Bubble Pop Game → Interactive cognitive engagement
- Finish Screen → Session completion and time tracking
The codebase underwent major refactoring to improve maintainability and contributor experience:
- Constants System: Centralized colors, text styles, sizes, and asset paths
- Utility Functions: Reusable functions for audio, navigation, and session management
- Common Widgets: Standardized UI components for consistent design
- Better Error Handling: Robust disposal patterns and lifecycle management
- Consistent Layout: All screens now follow the same responsive design pattern
- Centralized Theming: Material 3 theming with consistent colors and typography
- Asset Management: Organized asset declarations with proper error handling
- Code Organization: Modular structure makes it easier for contributors
- Documentation: Comprehensive inline documentation for all components
Purpose: Regulate breathing to activate the parasympathetic nervous system
Technique: 3-3-3 Breathing Method
- Inhale for 3 seconds
- Hold for 3 seconds
- Exhale for 3 seconds
Implementation:
- Visual breathing guide with expanding/contracting animation
- Dynamic text display (INHALE, HOLD, EXHALE)
- Rive animation integration
- 3-second timing for each phase
- Phase indicators with visual timing display
Mental Health Basis: Proven to reduce anxiety by stimulating the vagus nerve
Purpose: Ground users in the present moment through auditory focus
Available Sounds:
- Waves (Ocean sounds)
- Rain (Rainfall ambience)
- Birds (Nature bird sounds)
- Fire (Crackling fire)
- Forest (Forest ambience)
- Wind (Wind sounds)
Implementation:
- 6 high-quality audio tracks (music-1.mp3 to music-6.mp3)
- Play/pause controls
- Track selection with visual feedback
- Audio spectrum visualization animation
- Automatic audio cleanup on screen navigation
Mental Health Basis: Based on mindfulness and grounding techniques used in CBT
Purpose: Physical grounding through haptic feedback
Features:
- Start/Stop vibration controls
- Continuous vibration pattern for grounding
- Visual Rive animation accompaniment
- Device vibration capability detection
Implementation:
- Platform-specific vibration APIs
- Simple on/off vibration control
- Rive animation integration (vibrationAni.riv)
- Battery-conscious usage
- Accessibility considerations
Mental Health Basis: Somatic experiencing and body-based anxiety relief
Purpose: Engage olfactory memory for calming visualization
Visual Elements:
- Beautiful flower and nature imagery (F1.png - F8.png)
- Aesthetically pleasing visual arrangements
- Calming color palettes
- Multiple visual prompts for imagination
Implementation:
- High-quality imagery positioned across the screen
- Responsive design adapting to different screen sizes
- Visual-based imagination prompts
- Customizable duration
Mental Health Basis: Olfactory system's direct connection to limbic system
Purpose: Distraction through detailed sensory imagination
Visual Elements:
- Sweet treats and desserts (cupcake, doughnut, pancake)
- Refreshing beverages (milkshake, ice cream)
- Fresh fruits (pineapple)
- Appetizing food imagery
Implementation:
- Appetizing imagery positioned throughout the interface
- Visual prompts for taste imagination
- Multi-sensory engagement through appealing visuals
- Pleasant association building through food imagery
Mental Health Basis: Cognitive distraction and positive association therapy
Purpose: Interactive cognitive redirection through focused gameplay
Gameplay:
- Sequential bubble popping (numbers 1-20)
- Colorful gradient bubbles with satisfying pop sounds
- Non-overlapping bubble placement for clear targeting
- Immediate audio feedback with random pop sound selection
Implementation:
- Custom bubble painter with gradient effects and highlights
- Collision detection for proper bubble placement
- Audio player with multiple pop sound variants (pop1.mp3, pop2.mp3, pop3.mp3)
- Responsive design adapting to different screen sizes
- Progress tracking through sequential number system
- Note: Currently resets session time when navigating to finish screen
Mental Health Basis: Cognitive engagement therapy and mindful distraction techniques
# Flutter SDK (3.0+)
flutter --version
# IDE with Flutter plugin
# VS Code, Android Studio, or IntelliJ
# Git for version control
git --version# 1. Fork and clone
git clone https://github.com/YOUR-USERNAME/Calm-Attack.git
cd Calm-Attack
# 2. Install dependencies
flutter pub get
# 3. Run the app
flutter run
# 4. Run tests
flutter test- Unit Tests: Core logic and utilities
- Widget Tests: UI components
- Integration Tests: Full user flows
- Accessibility Tests: Screen reader compatibility
- Platform Tests: iOS and Android specific features
dependencies:
flutter:
sdk: flutter
provider: ^6.1.2 # State management (currently unused)
audioplayers: ^6.0.0 # Audio playback
rive: ^0.13.20 # Animations
vibration: ^3.1.3 # Haptic feedback
cupertino_icons: ^1.0.2 # iOS-style icons
dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^6.0.0 # Code quality
flutter_launcher_icons: ^0.13.1 # App icon generation- Code Quality: Automated linting and formatting
- Testing: Unit, widget, and integration tests
- Security: Dependency vulnerability scanning
- Build: Multi-platform compilation
- Release: Automated changelog generation
/* Primary Colors */
--primary-blue: #052D94 /* Deep calming blue */
--secondary-blue: #1E3A8A /* Medium blue */
--accent-blue: #3B82F6 /* Bright blue */
/* Neutral Colors */
--background: #FFFFFF /* Clean white */
--surface: #F8FAFC /* Light gray */
--text-primary: #1F2937 /* Dark gray */
--text-secondary: #6B7280 /* Medium gray */
/* Semantic Colors */
--success: #10B981 /* Green for completion */
--warning: #F59E0B /* Orange for attention */
--error: #EF4444 /* Red for errors */- Headers: Bold, clear hierarchy
- Body Text: High contrast, readable fonts
- Interactive Elements: Clear, actionable text
- Accessibility: Minimum 16px font size
- Whitespace: Generous spacing to reduce cognitive load
- Hierarchy: Clear information architecture
- Consistency: Predictable patterns throughout
- Responsiveness: Adapts to all screen sizes
- Subtle: Non-distracting, calming motions
- Purposeful: Animations serve specific functions
- Accessible: Respect motion sensitivity preferences
- Performance: Smooth 60fps on all devices
- Zero Data Collection: No personal information gathered
- Offline First: All functionality works without internet
- Local Storage Only: Settings stored on device
- No Tracking: No analytics or usage monitoring
- Transparent: Open source means auditable privacy
- No Network Requests: Prevents data leakage
- Secure Storage: Device-level encryption for settings
- No Third-Party SDKs: Eliminates tracking vectors
- Code Auditing: Regular security reviews
- Vulnerability Response: Responsible disclosure process
- GDPR Compliant: No personal data processing
- COPPA Safe: Suitable for all ages
- HIPAA Considerations: Healthcare setting appropriate
- Accessibility Standards: WCAG 2.1 AA compliance
- Minimum SDK: API 21 (Android 5.0)
- Target SDK: Latest stable
- Permissions: Vibration only
- App Icon: Adaptive icon support
- Material Design: Platform-appropriate styling
- Minimum Version: iOS 12.0
- Target Version: Latest stable
- Permissions: Haptic feedback only
- App Icon: Multiple sizes provided
- Human Interface Guidelines: iOS design patterns
- Progressive Web App: Offline functionality
- Responsive Design: All screen sizes
- Accessibility: Full keyboard navigation
- Performance: Fast loading times
- 🧑💻 Developers: Code, architecture, testing
- 🎨 Designers: UI/UX, visual assets, animations
- 🧠 Mental Health Professionals: Technique validation, content review
- 📝 Writers: Documentation, content creation
- 🧪 Testers: Quality assurance, accessibility testing
- 🌍 Translators: Internationalization support
- README Credits: Contributor listing
- Release Notes: Feature acknowledgments
- GitHub Badges: Contribution recognition
- Community Spotlights: Regular contributor features
- Code Quality: Follow Dart conventions
- Testing: Include tests with contributions
- Documentation: Update docs with changes
- Mental Health Sensitivity: Consider vulnerable users
- Accessibility: Ensure inclusive design
- Grounding Techniques in CBT
- 3-3-3 Breathing Research
- Mindfulness for Anxiety
- Panic Attack Management
- GitHub Issues: Technical problems and bugs
- GitHub Discussions: Questions and ideas
- Email: FatimahAlabbas1@outlook.sa
- Documentation: This comprehensive guide
- Read our Contributing Guide
Your interest in Calm Attack means the world to us. Whether you're a user finding peace or a contributor building hope, you're part of something beautiful.
Together, we're transforming panic into peace, one breath at a time. 💙
"The best way to take care of the future is to take care of the present moment." - Thich Nhat Hanh
Made with 💙 by a person that care