personal-monitor-domain

Personal Monitor Domain Specification

This skill defines WHAT the my-daily-monitor dashboard should do — the panels, data sources, APIs, and features that make up a personal daily monitoring system. Use this as a reference when creating new panels or deciding what to build next.

When to Use

• You are planning which panel to build next
• You need API details for a specific data source
• You are composing multiple panels into an integrated dashboard
• You need to understand the priority ordering for incremental development

Target Panels Overview

#	Panel	Data Source	Priority	Status
1	Schedule / Calendar	Google Calendar API	P0 — Core	Implemented
2	Email Inbox	Gmail API (OAuth)	P0 — Core	Implemented
3	Feishu Messages	Feishu/Lark Open API	P0 — Core	Implemented
4	Stock Market	Finnhub API	P0 — Core	Implemented
5	News Feed	GNews / HackerNews	P0 — Core	Implemented
6	Code Status (CI/CD)	GitHub Actions API	P1 — Important	Implemented
7	Office Documents	Microsoft Graph API	P1 — Important	Implemented
8	Social Feed (Twitter)	Twitter API v2	P1 — Important	Implemented
9	Daily Finance	Manual / Spreadsheet	P1 — Important	Implemented
10	Weather	OpenWeatherMap / wttr.in	P1 — Important	Implemented
11	World Clock	Built-in (no API)	P2 — Nice to Have	Implemented
12	Map	MapLibre GL	P2 — Nice to Have	Implemented
13	AI Insights	LLM API (Groq/Ollama)	P2 — Nice to Have	Implemented
14	Xiaohongshu	Web scraping / API	P2 — Nice to Have	Partial
15	DevOps	Server probes	P2 — Nice to Have	Implemented
16	Quick Links	Static config	P3 — Extra	Implemented
17	Live News	YouTube embed	P3 — Extra	Implemented
18	My Monitors	Custom keywords	P3 — Extra	Implemented

Panel Details

1. Schedule / Calendar

Purpose: Show today's meetings, upcoming events, and agenda

API: Google Calendar API v3

• Auth: OAuth 2.0 (reuses Gmail credentials)
• Endpoint: GET /api/calendar?calendarId=primary
• Headers: X-Gmail-Client-Id, X-Gmail-Client-Secret, X-Gmail-Token

Data shape:

interface CalendarEvent {
  id: string;
  title: string;
  startTime: string;      // ISO 8601
  endTime: string;
  location?: string;
  isAllDay?: boolean;
  color?: string;
  meetingLink?: string;    // Zoom/Meet URL
}

Refresh interval: 5 minutes

2. Email Inbox

Purpose: Show unread emails, sender, subject, snippet

API: Gmail API v1

• Auth: OAuth 2.0 (Client ID + Client Secret + Refresh Token)
• Endpoint: GET /api/emails?maxResults=15&q=is:unread
• Headers: X-Gmail-Client-Id, X-Gmail-Client-Secret, X-Gmail-Token
• Server-side: Exchange refresh token for access token, call Gmail API

Data shape:

interface EmailMessage {
  id: string;
  from: string;
  subject: string;
  snippet: string;
  receivedAt: string;
  unread: boolean;
  labels?: string[];
}

Refresh interval: 2 minutes

3. Feishu Messages

Purpose: Show recent Feishu/Lark chat messages across all conversations

API: Feishu Open Platform API

• Auth: App ID + App Secret → tenant access token
• Endpoint: GET /api/feishu
• Headers: X-Feishu-App-Id, X-Feishu-App-Secret
• Server-side: Get tenant_access_token, fetch chat list, fetch recent messages

Data shape:

interface FeishuMessage {
  id: string;
  chatName: string;
  chatType: string;        // 'group' | 'p2p'
  avatar: string;
  senderName: string;
  content: string;
  imageUrl: string;
  timestamp: string;
  unread: boolean;
  chatId: string;
  recentMessages: FeishuRecentMsg[];
}

Refresh interval: 1 minute

4. Stock Market

Purpose: Track personal stock watchlist with prices, changes, sparklines

API: Finnhub Stock API

• Auth: Query param token=API_KEY
• Endpoint: GET /api/stocks?symbols=AAPL,MSFT,...
• Free tier: 60 requests/minute
• Server-side: Batch fetch quotes, return unified format

Data shape:

interface StockQuote {
  symbol: string;
  name: string;
  price: number | null;
  change: number | null;
  changePercent: number | null;
  high: number | null;
  low: number | null;
  sparkline?: number[];
}

Default watchlist: AAPL, MSFT, GOOGL, AMZN, TSLA, NVDA, META

Refresh interval: 1 minute

5. News Feed

Purpose: Aggregated headlines from multiple sources with threat classification

APIs:

• GNews (primary): https://gnews.io/api/v4 — 100 req/day free
• HackerNews (tech): https://hacker-news.firebaseio.com/v0/ — unlimited, no key
• RSS feeds (fallback): Direct XML parsing

Data shape:

interface NewsArticle {
  title: string;
  description: string;
  url: string;
  source: string;
  publishedAt: string;
  image?: string;
  threatLevel?: 'critical' | 'high' | 'medium' | 'low';
}

Refresh interval: 5 minutes

6. Code Status (CI/CD)

Purpose: Show GitHub Actions workflow runs — passed, failed, in-progress

API: GitHub REST API v3

• Auth: Personal Access Token (PAT) in GITHUB_TOKEN
• Endpoint: GET /api/github?action=runs&owner=...&repo=...
• Server-side: Fetch /repos/{owner}/{repo}/actions/runs

Data shape:

interface WorkflowRun {
  id: number;
  name: string;
  status: string;
  conclusion: string | null;   // 'success' | 'failure' | 'cancelled'
  branch: string;
  createdAt: string;
  url: string;
}

Refresh interval: 2 minutes

7. Office Documents

Purpose: Recent Office document activity (PPT, DOC, XLSX, PDF)

API: Microsoft Graph API

• Auth: OAuth 2.0 (Azure AD app registration)
• Endpoint: GET /api/office
• Server-side: Call Graph API /me/drive/recent

Data shape:

interface OfficeDocument {
  id: string;
  name: string;
  type: 'doc' | 'xlsx' | 'ppt' | 'pdf';
  modifiedAt: string;
  modifiedBy: string;
  url?: string;
}

Refresh interval: 5 minutes

Note: Currently uses demo data. Full implementation requires Azure AD app registration with Files.Read permission.

8. Social Feed

Purpose: Twitter timeline + Xiaohongshu content

Twitter API v2:

• Auth: Bearer Token
• Endpoint: GET /api/social?action=search&q=... or action=list&listId=...
• Server-side: Forward to Twitter search/list endpoint

Xiaohongshu:

• No official API; requires web scraping or reverse-engineered endpoints
• Potential approach: headless browser scraping via server-side proxy

Data shape:

interface SocialPost {
  id: string;
  platform: 'twitter' | 'xiaohongshu';
  author: string;
  username?: string;
  content: string;
  timestamp: string;
  likes?: number;
  retweets?: number;
  comments?: number;
  url?: string;
}

Refresh interval: 3 minutes

9. Daily Finance

Purpose: Track daily income and expenses, show balance

Data source options:

• Google Sheets API (personal budget spreadsheet)
• YNAB API (budgeting app)
• Local JSON file / localStorage
• Custom bookkeeping endpoint

Data shape:

interface DailySummary {
  totalIncome: number;
  totalExpense: number;
  balance: number;
  transactions: FinanceTransaction[];
}

interface FinanceTransaction {
  id: string;
  description: string;
  amount: number;
  type: 'income' | 'expense';
  category: string;
  date: string;
}

Refresh interval: 10 minutes

Composition: Today Focus Sidebar

The sidebar aggregates highlights from multiple panels into a single glanceable view:

interface TodayFocusData {
  nextEvent?: { title: string; startTime: string; minutesUntil: number };
  unreadEmails: number;
  unreadFeishu: number;
  stockAlerts: Array<{ symbol: string; changePercent: number }>;
  ciFailures: number;
  dailyBriefing?: string;   // AI-generated summary
}

Dependencies: schedule, email, feishu, stock-market, code-status, ai-summary

Composition: AI Daily Briefing

Uses an LLM to synthesize a morning briefing from all data sources:

Input: Unread emails, today's events, top news headlines, stock movers Output: 2-3 paragraph natural language summary API: Groq (free, fast) or local Ollama

API Key Configuration

All API keys are stored in browser localStorage via a Settings modal:

Key	Required For	How to Get
FINNHUB_API_KEY	Stock Market	https://finnhub.io/ (free)
GNEWS_API_KEY	News	https://gnews.io/ (free, 100/day)
GMAIL_CLIENT_ID	Email + Calendar	Google Cloud Console OAuth
GMAIL_CLIENT_SECRET	Email + Calendar	Google Cloud Console OAuth
GMAIL_REFRESH_TOKEN	Email + Calendar	OAuth flow
FEISHU_APP_ID	Feishu	Feishu Open Platform
FEISHU_APP_SECRET	Feishu	Feishu Open Platform
GITHUB_TOKEN	Code Status	GitHub → Settings → PAT
TWITTER_BEARER_TOKEN	Social Feed	Twitter Developer Portal
GROQ_API_KEY	AI Insights	https://console.groq.com/

Keys are passed to the server via request headers (never in query params), and the server-side proxy uses them to call external APIs.

Personal Data Sensitivity

This dashboard handles personal data. Key considerations:

1. API keys — stored in localStorage, never sent to third parties
2. Email content — proxied through your own server, not cached
3. Calendar events — may contain sensitive meeting details
4. Finance data — keep local, never expose to external APIs
5. Social accounts — use read-only tokens, never write access
6. No analytics — unlike WorldMonitor, no Sentry/Vercel Analytics needed
7. Self-hosted — run on localhost or personal server, not public deployment

Development Priority

Phase 1 (MVP): Schedule + Email + Feishu + Stock + News — the daily essentials Phase 2 (Complete): Code Status + Office + Social + Finance + Weather Phase 3 (Enhanced): Map + AI Insights + World Clock + Xiaohongshu Phase 4 (Polish): DevOps + Live News + Quick Links + My Monitors + Command Palette