> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lopiv2/invenicum/llms.txt
> Use this file to discover all available pages before exploring further.

# Achievements

> Track your inventory management progress with the achievement system

## Overview

The Invenicum achievement system gamifies your inventory management experience by recognizing milestones and accomplishments. As you use the platform, you'll unlock achievements that showcase your progress and expertise.

## Achievement System

### How Achievements Work

Achievements are automatically tracked based on your activity:

```dart theme={null}
// From achievement_provider.dart:25
Future<void> fetchAchievements(BuildContext context) async {
  _isLoading = true;
  notifyListeners();
  
  try {
    // Get user progress from server
    final List<Map<String, dynamic>> serverData = 
        await _service.getAchievements();
    
    // Merge with static definitions (icons, text)
    final staticDefs = AppAchievements.getDefinitions(context);
    
    _achievements = staticDefs.map((staticDef) {
      final serverMatch = serverData.firstWhere(
        (s) => s['id'].toString() == staticDef.id,
        orElse: () => {},
      );
      
      return AchievementDefinition(
        id: staticDef.id,
        title: staticDef.title,
        desc: staticDef.desc,
        icon: staticDef.icon,
        category: staticDef.category,
        isLegendary: staticDef.isLegendary,
        unlocked: serverMatch['unlocked'] ?? false,
        unlockedAt: serverMatch['unlockedAt'] != null 
            ? DateTime.parse(serverMatch['unlockedAt']) 
            : null,
      );
    }).toList();
  } finally {
    _isLoading = false;
    notifyListeners();
  }
}
```

The system:

1. **Monitors Activity** - Tracks actions you perform in the app
2. **Checks Conditions** - Evaluates if achievement criteria are met
3. **Unlocks Achievements** - Automatically awards achievements when earned
4. **Persists Progress** - Saves your achievement state to the cloud

### Achievement Structure

Each achievement has:

<CardGroup cols={2}>
  <Card title="Metadata" icon="info-circle">
    * Unique ID
    * Title and description
    * Category classification
    * Legendary status
  </Card>

  <Card title="Progress" icon="chart-line">
    * Locked/Unlocked status
    * Unlock timestamp
    * Progress percentage (for tracked achievements)
  </Card>
</CardGroup>

## Achievement Categories

Achievements are organized into categories:

### General

Core milestones in using Invenicum:

* Creating your first collection
* Adding your first item
* Completing your profile
* Using the mobile app

### Collections

Collection management achievements:

* Create multiple collections
* Set up collection goals
* Share collections with others
* Organize with custom fields

### Items

Inventory item milestones:

* Add specific quantities of items
* Use barcode scanning
* Attach images to items
* Complete detailed item information

### Valuation

Value tracking progress:

* Record purchase prices
* Track value changes over time
* Reach collection value milestones
* Use pricing integrations

### Organization

Organizational achievements:

* Use locations and containers
* Create custom asset types
* Implement tagging systems
* Set up hierarchical structures

### Social

Community participation:

* Share templates
* Publish plugins
* Help other users
* Contribute to marketplace

### Legendary

Rare, difficult achievements:

* Major milestones (1000+ items)
* Perfect organization (100% completion)
* Community recognition
* Long-term dedication

## Viewing Achievements

### Achievement Screen

Access your achievements from the profile or settings menu:

<Steps>
  <Step title="Open Achievements">
    Navigate to Profile → Achievements or Settings → Achievements.
  </Step>

  <Step title="View Progress">
    See your overall completion:

    ```dart theme={null}
    // From achievement_provider.dart:18
    int get unlockedCount => _achievements.where((a) => a.unlocked).length;

    double get progressPercentage => _achievements.isEmpty 
        ? 0 
        : (unlockedCount / _achievements.length);
    ```
  </Step>

  <Step title="Browse Categories">
    Filter achievements by category to focus on specific areas.
  </Step>

  <Step title="Check Details">
    Tap any achievement to see:

    * Detailed description
    * Unlock requirements
    * Unlock date (if achieved)
    * Progress toward completion
  </Step>
</Steps>

### Achievement Cards

Achievements are displayed with visual indicators:

* **Unlocked**: Full color with unlock date
* **Locked**: Grayscale with progress bar (if applicable)
* **Legendary**: Special golden border and effects

## Unlocking Achievements

### Automatic Unlocking

Most achievements unlock automatically when you meet the criteria:

```dart theme={null}
// From achievements_service.dart:22
Future<void> triggerAction(String actionType, dynamic value) async {
  try {
    await _dio.post('/achievements/check', data: {
      'action': actionType,
      'value': value,
    });
  } catch (e) {
    // Silent error to not interrupt UX
  }
}
```

The backend automatically:

1. Receives action notifications
2. Checks achievement criteria
3. Updates achievement status
4. Returns new achievements to the app

### Manual Checks

Force a refresh of achievement status:

```dart theme={null}
// From achievement_provider.dart:83
Future<void> checkAchievementsStatus(BuildContext context) async {
  await fetchAchievements(context);
}
```

Use this after:

* Completing a major task
* Returning from background
* Syncing data
* Manual refresh

## Achievement Types

### Threshold Achievements

Unlocked when reaching specific numbers:

<Accordion title="Examples">
  * **First Steps**: Add your first item
  * **Growing Collection**: Reach 10 items
  * **Serious Collector**: Reach 100 items
  * **Museum Curator**: Reach 1,000 items
  * **Legendary Archive**: Reach 10,000 items
</Accordion>

### Action Achievements

Unlocked by performing specific actions:

<Accordion title="Examples">
  * **Photographer**: Add an image to an item
  * **Scanner**: Use barcode scanning
  * **Organizer**: Create a location hierarchy
  * **Valuation Expert**: Track price changes
  * **Collaborator**: Share a collection
</Accordion>

### Time-Based Achievements

Unlocked based on duration or dates:

<Accordion title="Examples">
  * **Dedicated User**: Use app 7 days in a row
  * **Monthly Regular**: Use app every month for 6 months
  * **Anniversary**: Use app for 1 year
  * **Early Adopter**: Create account in first month
</Accordion>

### Completionist Achievements

Unlocked by finishing comprehensive tasks:

<Accordion title="Examples">
  * **Profile Complete**: Fill all profile fields
  * **Collection Master**: Complete all fields for every item
  * **Full Documentation**: Add images to all items
  * **Perfect Organization**: Assign locations to all items
</Accordion>

### Social Achievements

Unlocked through community interaction:

<Accordion title="Examples">
  * **Template Publisher**: Publish a template
  * **Plugin Creator**: Create a plugin
  * **Community Helper**: Template downloaded 100 times
  * **Popular Creator**: Plugin used by 50+ users
</Accordion>

## Achievement Progress Tracking

### Progress Indicators

Some achievements show progress before unlocking:

```dart theme={null}
// Example: Track progress toward "100 Items" achievement
final currentCount = 47;
final requiredCount = 100;
final progress = currentCount / requiredCount; // 0.47 or 47%
```

Progress appears as:

* Progress bar on locked achievements
* Numerical display (e.g., "47/100")
* Percentage completion

### Formatted Dates

Unlock dates are displayed in user-friendly format:

```dart theme={null}
// From achievement_provider.dart:70
String getFormattedDate(String achievementId) {
  try {
    final ach = _achievements.firstWhere((a) => a.id == achievementId);
    if (ach.unlockedAt == null) return '';
    
    return DateFormat.yMMMd().format(ach.unlockedAt!);
  } catch (e) {
    return '';
  }
}
```

Example output: "24 Feb. 2024"

## Achievement Model

Achievement data structure:

```dart theme={null}
// From achievements_model.dart:3
class AchievementDefinition {
  final String id;
  final String title;
  final String desc;
  final IconData icon;
  final String category;
  final bool isLegendary;
  final bool unlocked;
  final DateTime? unlockedAt;
  
  const AchievementDefinition({
    required this.id,
    required this.title,
    required this.desc,
    required this.icon,
    this.category = 'general',
    this.isLegendary = false,
    this.unlocked = false,
    this.unlockedAt,
  });
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Natural Progression" icon="seedling">
    Don't focus too heavily on achievements. Let them unlock naturally as you use Invenicum effectively.
  </Card>

  <Card title="Quality Over Quantity" icon="gem">
    Rather than rushing to unlock achievements, focus on organizing your inventory well.
  </Card>

  <Card title="Explore Features" icon="compass">
    Achievements highlight app features you might not have discovered yet.
  </Card>

  <Card title="Share Success" icon="share-nodes">
    Legendary achievements are worth celebrating with the community!
  </Card>
</CardGroup>

## Benefits of Achievements

### Motivation

Achievements provide tangible goals and recognition for your organizational efforts.

### Discovery

Unlocking achievements often introduces you to features you haven't tried yet.

### Progress Tracking

Visual representation of your growth as an inventory manager.

### Community

Compare progress with other users and celebrate milestones together.

### Gamification

Makes routine inventory management more engaging and rewarding.

## Tips for Achievement Hunters

<AccordionGroup>
  <Accordion title="Start with Basics">
    Focus on fundamental achievements first:

    1. Complete your profile
    2. Create your first collection
    3. Add your first items
    4. Upload your first images
    5. Set up basic organization

    These unlock quickly and familiarize you with core features.
  </Accordion>

  <Accordion title="Explore All Features">
    Many achievements require using different parts of the app:

    * Try barcode scanning
    * Set up integrations
    * Use locations and containers
    * Create custom fields
    * Share with others

    Comprehensive exploration unlocks diverse achievements.
  </Accordion>

  <Accordion title="Be Consistent">
    Time-based achievements require regular use:

    * Open the app daily
    * Make incremental progress
    * Update your collections regularly
    * Engage with the community

    Consistency unlocks duration-based achievements.
  </Accordion>

  <Accordion title="Quality Documentation">
    Completionist achievements reward thoroughness:

    * Add images to all items
    * Fill custom fields completely
    * Write detailed descriptions
    * Organize with locations

    Well-documented collections unlock multiple achievements.
  </Accordion>
</AccordionGroup>

## Legendary Achievements

Legendary achievements are the most prestigious:

<Note>
  Legendary achievements often require significant dedication, major milestones, or exceptional contributions to the community. They're designed to be rare and meaningful.
</Note>

**Characteristics of Legendary Achievements:**

* Difficult criteria (e.g., 10,000+ items)
* Long-term commitment required
* Significant community contribution
* Perfect completion metrics
* Rare circumstances or timing

**Special Recognition:**

* Golden border and effects
* Profile badge display
* Community leaderboard presence
* Exclusive features or cosmetics (future)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Achievement Not Unlocking">
    If you believe you've met the criteria but the achievement hasn't unlocked:

    1. **Refresh**: Pull down on the achievements screen to sync
    2. **Check Criteria**: Verify you've actually met all requirements
    3. **Wait**: Some achievements have a brief processing delay
    4. **Reconnect**: Ensure you have internet connectivity
    5. **Contact Support**: If the issue persists, report it
  </Accordion>

  <Accordion title="Progress Not Updating">
    If progress bars aren't reflecting your current status:

    1. **Force Refresh**: Use the manual refresh button
    2. **Check Sync**: Ensure data has synced to cloud
    3. **Restart App**: Close and reopen the application
    4. **Verify Data**: Confirm your actions are being recorded
  </Accordion>

  <Accordion title="Missing Achievements">
    If you can't see some achievements:

    1. **Update App**: Ensure you have the latest version
    2. **Check Category**: Look in the correct category
    3. **Feature Access**: Some achievements require specific features or integrations
    4. **Account Status**: Verify your account is in good standing
  </Accordion>
</AccordionGroup>

## Future Achievement Updates

<Info>
  The achievement system is regularly updated with:

  * New achievements for new features
  * Seasonal and event achievements
  * Community-suggested achievements
  * Refined criteria based on feedback

  Stay tuned for announcements about new achievements!
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Profile Settings" icon="user" href="/account/profile">
    Complete your profile to unlock achievements
  </Card>

  <Card title="Collections" icon="box" href="/collections/overview">
    Create collections to progress toward milestones
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/advanced/plugins">
    Publish plugins for community achievements
  </Card>

  <Card title="Templates" icon="layer-group" href="/advanced/templates">
    Share templates to unlock creator achievements
  </Card>
</CardGroup>