Skip to Content
AgentsOverview

Dashboard Expert AI Agent Documentation

Welcome to the Dashboard Expert AI Agent documentation! This collection of documents enables Claude (or any AI assistant) to become an expert in the Oter Dashboard feature.

What is This?

This is a comprehensive knowledge base that transforms a general-purpose AI into a specialized Dashboard feature expert. By loading these documents, Claude gains deep understanding of:

  • Dashboard architecture and design patterns
  • API endpoints and their usage
  • Core algorithms (next task/habit selection, overdue detection)
  • Common development tasks
  • Troubleshooting procedures

Documentation Structure

/docs/agents/
├── README.md                          # This file - usage guide
├── dashboard-expert-prompt.md         # System prompt for AI expertise
├── dashboard-api-reference.md         # Complete API documentation
├── dashboard-architecture.md          # Architecture deep-dive
├── dashboard-common-tasks.md          # Developer cookbook
└── dashboard-troubleshooting.md       # Debugging guide

Quick Start

Option 1: Using Claude Code CLI

If you’re using Claude Code, you can reference the expert prompt to get dashboard-specific help:

# Ask a question with dashboard expertise
claude-code "Why is my weekly habit showing as overdue on Tuesday?"
 
# The agent documentation is available in the codebase, so Claude Code can reference it

Option 2: Loading the System Prompt

For other AI tools or direct Claude usage, load the expert prompt:

# Copy the prompt to use in any AI conversation
cat docs/agents/dashboard-expert-prompt.md
 
# Or use it programmatically
claude-code --prompt "$(cat docs/agents/dashboard-expert-prompt.md)" \
  "Help me add a new metric to the dashboard"

Option 3: Using as Reference Documentation

The documentation files are also excellent human-readable references:

  • API Reference - For frontend/integration developers
  • Architecture Guide - For understanding system design
  • Common Tasks - For step-by-step development guides
  • Troubleshooting - For debugging issues

Usage Examples

Example 1: Debugging Overdue Habits

Question: “My daily habit set for 9 AM is showing as overdue at 8 AM. Why?”

With Dashboard Expert Loaded: Claude will:

  1. Reference the overdue detection algorithm in dashboard-expert-prompt.md
  2. Explain that DAILY habits use nextOccurrenceDateTime logic
  3. Point to line 540-547 in DashboardService.kt
  4. Provide debugging steps from dashboard-troubleshooting.md
  5. Suggest checking timezone consistency

Answer:

The daily habit overdue detection checks if now > nextOccurrenceDateTime. For your habit scheduled at 9 AM, the next occurrence is today at 9:00 AM. At 8 AM, now (8:00 AM) is NOT greater than nextOccurrenceDateTime (9:00 AM), so it should NOT be overdue.

This suggests a timezone mismatch. Check:

  1. Server timezone: The dateTime parameter you’re sending
  2. Habit’s stored dateTime in the database

See DashboardService.kt:540-547 for the exact logic.

Example 2: Adding New Metrics

Question: “How do I add a ‘mood tracker’ metric to the dashboard?”

With Dashboard Expert Loaded: Claude will:

  1. Reference the “Adding New Metrics” section in dashboard-common-tasks.md
  2. Provide step-by-step instructions
  3. Reference exact file paths and line numbers
  4. Include code examples following existing patterns

Answer:

To add mood tracker to the dashboard:

  1. Add field to DashboardResponseDTO:

    val todayMood: String? = null,
val weeklyMoodTrend: Float = 0f

  2. Add service dependency in DashboardService.kt:23-31:

    private val moodService: MoodService

  3. Fetch data in getDashboardData (around line 95):

    val todayMood = moodService.getMoodForDate(userId, today)

  4. Include in response (line 125-155)

See dashboard-common-tasks.md for complete guide.

Example 3: Understanding Next Habit Algorithm

Question: “How does the system decide which habit to show as ‘next’?”

With Dashboard Expert Loaded: Claude will:

  1. Reference the algorithm section in dashboard-expert-prompt.md
  2. Explain the multi-step process
  3. Provide code references
  4. Give examples with different frequencies

Answer:

The Next Habit selection (DashboardService.kt:297-399) follows this algorithm:

  1. Calculate next occurrence for each pending habit based on frequency:

    • DAILY: Today if time hasn’t passed, else tomorrow
    • WEEKLY: Next occurrence of target day of week
    • MONTHLY: Next occurrence of target day of month
    • YEARLY: Next occurrence of target day of year

  2. Filter overdue: Remove habits where now > nextOccurrenceDateTime

  3. Prioritize:

    • Future times today (sorted earliest first)
    • Past times today (sorted earliest first)
    • Future dates (sorted earliest first)

Example: It’s Tuesday 2 PM. You have:

  • Habit A: Daily at 6 PM → Next: Today 6 PM (future time today) ✓ SELECTED
  • Habit B: Daily at 10 AM → Next: Tomorrow 10 AM (overdue, filtered out)
  • Habit C: Weekly on Wednesday at 9 AM → Next: Tomorrow 9 AM (future date)

Result: Habit A is selected (highest priority category).

Example 4: API Usage

Question: “What’s the correct way to fetch dashboard data?”

With Dashboard Expert Loaded: Claude will:

  1. Reference dashboard-api-reference.md
  2. Provide exact endpoint, parameters, and examples
  3. Show authentication requirements
  4. Include error handling

Answer:

Use the GET /api/v1/dashboard endpoint:

curl -X GET "http://localhost:8080/api/v1/dashboard?dateTime=2024-01-16T14:30:00" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Required:

  • dateTime query parameter in ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
  • JWT Bearer token with userId claim

Returns: DashboardResponseDTO with 40+ fields

Common errors:

  • 401: Missing/invalid token
  • 400: Missing or malformed dateTime

See dashboard-api-reference.md for complete API docs.

Document Descriptions

dashboard-expert-prompt.md

Purpose: System prompt that encodes complete dashboard expertise

Contents:

  • Core competencies and knowledge areas
  • API endpoint specifications
  • Algorithm implementations with line numbers
  • Service dependencies and data flow
  • Data model structures
  • Debugging patterns and testing knowledge
  • Performance considerations
  • Extension points

Use When: You want Claude to act as a Dashboard feature expert

Size: ~4,000 words

dashboard-api-reference.md

Purpose: Complete REST API documentation

Contents:

  • All 3 dashboard endpoints with examples
  • Request/response formats
  • Authentication requirements
  • Error codes and handling
  • cURL examples
  • Data type definitions
  • Implementation details

Use When: Integrating with dashboard API, writing frontend code, or testing

Size: ~2,500 words

dashboard-architecture.md

Purpose: Deep-dive into system architecture and design

Contents:

  • Layered architecture explanation
  • Data flow diagrams (textual)
  • Service dependencies graph
  • Algorithm implementations (detailed)
  • Database schema
  • Testing architecture
  • Design patterns used
  • Performance considerations

Use When: Understanding system design, planning refactoring, or conducting code reviews

Size: ~5,000 words

dashboard-common-tasks.md

Purpose: Developer cookbook with step-by-step guides

Contents:

  • Adding new metrics
  • Modifying task/habit selection logic
  • Adding widget types
  • Implementing new frequency types
  • Debugging techniques
  • Performance optimization
  • Platform support
  • Testing strategies

Use When: Implementing new features or modifying existing behavior

Size: ~6,000 words

dashboard-troubleshooting.md

Purpose: Diagnostic guide for common issues

Contents:

  • 10 common problem categories
  • Symptoms, causes, and solutions
  • Debugging steps with SQL queries
  • Code examples and fixes
  • General debugging checklist

Use When: Debugging issues or investigating unexpected behavior

Size: ~5,500 words

Tips for Effective Use

1. Be Specific in Questions

Better:

“Why does my weekly habit with baseDate Wednesday show as overdue on Thursday at 10 AM when the base time is 9 AM?”

Not as good:

“Habits aren’t working right”

2. Reference Specific Scenarios

Better:

“I have a monthly habit scheduled for the 15th at 2 PM. Today is the 16th at 10 AM. Should it be overdue?”

Not as good:

“How do monthly habits work?“

3. Include Error Messages

Better:

“I’m getting ‘Invalid date time format’ when I send dateTime=2024-01-16 14:30:00. What’s wrong?”

Not as good:

“The API isn’t working”

4. Specify Your Goal

Better:

“I want to prioritize habits with longer streaks to maintain momentum. How do I modify the next habit algorithm?”

Not as good:

“How do I change habit selection?”

Extending the Agent

Adding Knowledge for New Features

When you add new dashboard functionality:

  1. Update dashboard-expert-prompt.md: Add new algorithm details, API changes
  2. Update dashboard-api-reference.md: Document new endpoints or fields
  3. Update dashboard-architecture.md: Explain architectural changes
  4. Add to dashboard-common-tasks.md: Create guide for the new feature
  5. Add to dashboard-troubleshooting.md: Document common issues

Example: Adding Notification Support

If you add dashboard notifications:

In dashboard-expert-prompt.md:

### 10. Notification System
 
**File**: `DashboardNotificationService.kt`
 
The dashboard can send notifications when:
- Tasks become overdue
- Habits are due in next 30 minutes
- Weekly goals are achieved
 
**Algorithm**: Checks every 15 minutes via scheduled job...

In dashboard-api-reference.md:

### 4. Get Pending Notifications
 
**Endpoint**: `GET /api/v1/dashboard/notifications`
...

In dashboard-common-tasks.md:

## Adding New Notification Types
 
Step 1: Define notification type...

In dashboard-troubleshooting.md:

## Notifications Not Sending
 
### Symptoms
- Expected notifications not appearing
...

Maintenance

Keeping Documentation Current

When to update:

  • After refactoring dashboard code
  • When adding/removing features
  • When fixing bugs that reveal incorrect documentation
  • After performance optimizations

What to update:

  • Line number references if code structure changed
  • Algorithm descriptions if logic changed
  • API examples if endpoint format changed
  • File paths if files were moved/renamed

Version Tracking

Consider adding version/date to each document:

# Dashboard Expert AI Agent - System Prompt
 
**Version**: 1.0
**Last Updated**: 2024-01-16
**Compatible with**: Oter Server v2.5+

Contributing

When improving this documentation:

  1. Maintain consistency: Follow the established format and style
  2. Be specific: Include file paths, line numbers, and code examples
  3. Test accuracy: Verify all code examples work
  4. Update cross-references: If changing one doc, update related docs
  5. Add examples: Real-world examples are more valuable than abstract descriptions

Support

For Documentation Issues:

  • Create an issue if documentation is incorrect
  • Submit PR with corrections
  • Add missing troubleshooting scenarios

For Dashboard Feature Issues:

  • Check dashboard-troubleshooting.md first
  • Review debug logs with patterns from documentation
  • Create unit test reproducing the issue
  • Reference algorithm documentation when reporting bugs

License

This documentation is part of the Oter project and follows the same license.

Remember: These documents are designed to make Claude an expert in the Dashboard feature. The more context and detail you provide in your questions, the more accurate and helpful the AI responses will be!

InfraExpert system prompt