From c174f3c1d46e120ca4ca79d4e5e755996bb02ed7 Mon Sep 17 00:00:00 2001 From: Drew Peifer Date: Thu, 12 Feb 2026 03:31:07 -0500 Subject: [PATCH] fleshed out readme --- README.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 195 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 954f170..bd96ed9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,195 @@ -# personal-dash-cl -SPA that generates a customizable dashboard / briefing powered by Anthropic / Claude +# Personal Dashboard (ClauDash) + +A React-based personal dashboard application that generates AI-powered daily briefings using Claude (Anthropic). The app aggregates data from multiple configurable sources—including weather, news APIs, Reddit, Hacker News, and RSS feeds—and uses Claude to create personalized, conversational briefings that highlight what's interesting and track changes over time. Includes an interactive chat interface and intelligent caching to minimize API usage. + +## Quick Setup + +After cloning the repository, follow these steps to get started: + +1. **Install dependencies** + ```bash + cd claudash + npm install + ``` + +2. **Configure environment variables** + ```bash + cp .env.example .env.local + ``` + Edit `.env.local` and add your Anthropic API key: + ``` + REACT_APP_ANTHROPIC_API_KEY=sk-ant-your-actual-key-here + ``` + +3. **Configure your data sources and location** (optional) + + In `.env.local`, customize these settings: + - `REACT_APP_LOCATION` - Your location for weather (e.g., "harrisburg, pa, usa") + - `REACT_APP_DATA_SOURCES` - Comma-separated URLs to fetch from + - `REACT_APP_CLAUDE_INSTRUCTIONS` - Custom instructions for briefing tone/focus + +4. **Start the application** + ```bash + npm start + ``` + This command runs both the Vite dev server (port 5173) and the proxy server (port 3001) concurrently. + +5. **Access the dashboard** + + Open your browser to `http://localhost:5173` + +## How It Works + +### Architecture + +The application consists of three main layers: + +1. **Data Fetching Layer** (`src/services/dataFetcher.js`) + - Fetches data from configured sources (Reddit JSON APIs, Hacker News, RSS feeds, etc.) + - Retrieves weather information from wttr.in + - Implements intelligent caching with configurable TTL to minimize API calls + - Handles multiple data sources in parallel with graceful error handling + +2. **AI Processing Layer** (`src/services/claudeService.js`) + - Sends aggregated data to Claude via a local Express proxy server + - Builds context-aware prompts that include yesterday's briefing for comparison + - Generates personalized briefings (300-400 words) with personality and insights + - Tracks token usage and estimated API costs + - Provides a chat interface for follow-up questions + +3. **Presentation Layer** (`src/components/`) + - Material-UI widgets display briefing, weather, and news data + - Drag-and-drop capable widget layout (via MUI flex grid) + - Dark/light theme toggle + - Chat interface for conversational interaction with Claude + - Debug panel for development (toggleable via env variable) + +### Data Flow + +1. **On Load**: Dashboard checks localStorage for today's cached briefing +2. **If Not Cached**: Fetches data from all configured sources in parallel +3. **Data Aggregation**: Combines weather and news data with standardized schema +4. **AI Generation**: Sends data + yesterday's briefing to Claude for context-aware briefing +5. **Caching**: Stores briefing and raw data in localStorage with timestamps +6. **Display**: Renders briefing and individual source widgets +7. **Refresh**: Manual refresh button forces fresh data fetch and new briefing generation + +### Proxy Server + +The application uses a local Express proxy server (`proxy-server.js`) to communicate with the Anthropic API. This is necessary because: +- Browser CORS restrictions prevent direct API calls from the frontend +- Keeps the API key secure from browser developer tools +- Provides a single point for API request/response logging + +### Source Parser + +The `sourceParser.js` service intelligently handles various data formats: +- **JSON APIs**: Reddit, Hacker News, custom JSON endpoints +- **RSS/XML Feeds**: Parses RSS feeds with full article content +- **HTML Pages**: Uses Claude to extract and summarize web page content +- **Weather**: Standardizes wttr.in weather data into a consistent format + +All sources are normalized into a common schema before being sent to Claude. + +### Storage & Caching + +The app uses localStorage for two types of caching: + +1. **Briefing History**: Stores daily briefings with dates for historical context +2. **Source Data Cache**: Short-term cache (default 15 min) for API responses to avoid redundant fetches + +The `storageService.js` handles all persistence with automatic cleanup of old data based on `REACT_APP_HISTORY_DAYS`. + +## Features + +- **AI-Powered Briefings**: Claude generates conversational, personalized summaries +- **Historical Context**: Compares today's news with yesterday's to highlight changes and follow-ups +- **Multiple Data Sources**: Configure any combination of JSON APIs, RSS feeds, or web pages +- **Smart Caching**: Reduces API calls and costs through intelligent data caching +- **Interactive Chat**: Ask Claude follow-up questions about your briefing +- **Token Tracking**: Real-time display of API usage and estimated costs +- **Theme Support**: Toggle between light and dark themes +- **Responsive Layout**: Flexible widget grid adapts to screen size +- **Weather Integration**: Location-based weather pulled from wttr.in +- **Debug Mode**: Developer tools for testing and troubleshooting + +## Configuration Options + +All configuration is done via environment variables in `.env.local`: + +| Variable | Description | Default | +|----------|-------------|---------| +| `REACT_APP_ANTHROPIC_API_KEY` | Your Anthropic API key (required) | - | +| `REACT_APP_LOCATION` | Location for weather | - | +| `REACT_APP_DATA_SOURCES` | Comma-separated URLs | Reddit & HN | +| `REACT_APP_CLAUDE_MODEL` | Claude model to use | claude-sonnet-4-5-20250929 | +| `REACT_APP_CLAUDE_INSTRUCTIONS` | Custom briefing instructions | - | +| `REACT_APP_REFRESH_INTERVAL` | Cache TTL in minutes | 15 | +| `REACT_APP_HISTORY_DAYS` | Days of history to keep | 7 | +| `REACT_APP_CORS_PROXY` | Custom CORS proxy URL | allorigins.win | +| `REACT_APP_DEBUG_MODE` | Enable debug features | false | + +## Project Structure + +``` +claudash/ +├── proxy-server.js # Express proxy for Anthropic API +├── src/ +│ ├── components/ +│ │ ├── Dashboard.jsx # Main dashboard container +│ │ ├── ChatInterface.jsx # Floating chat widget +│ │ └── widgets/ # Individual data display widgets +│ ├── services/ +│ │ ├── claudeService.js # Claude API integration +│ │ ├── dataFetcher.js # Multi-source data fetching +│ │ ├── sourceParser.js # Parse various data formats +│ │ └── storageService.js # localStorage management +│ └── utils/ +│ ├── constants.js # App-wide constants +│ └── corsProxy.js # CORS proxy utilities +``` + +## Major Dependencies + +- **[React](https://react.dev/)** (v19) - UI framework +- **[Material-UI](https://mui.com/)** (v7) - Component library and design system +- **[Emotion](https://emotion.sh/)** - CSS-in-JS styling for MUI +- **[Vite](https://vitejs.dev/)** (v4) - Build tool and dev server +- **[Express](https://expressjs.com/)** (v5) - Proxy server for API communication +- **[Anthropic Claude API](https://www.anthropic.com/)** - AI-powered text generation + +## Development + +### Running in Development Mode + +```bash +npm start # Runs both dev server and proxy +npm run dev # Run only Vite dev server +npm run proxy # Run only proxy server +``` + +### Building for Production + +```bash +npm run build # Creates optimized production build +npm run preview # Preview production build locally +``` + +### Debugging + +Set `REACT_APP_DEBUG_MODE=true` in `.env.local` to enable: +- Debug panel with raw data inspection +- Console logging for API calls +- Dummy data generation for testing + +## Tips & Best Practices + +- **API Costs**: The app displays token usage and estimated costs after each briefing generation. Typical briefings cost $0.02-0.05 depending on data source complexity. +- **Caching**: Briefings are cached per day; use the refresh button to force a new generation. +- **Custom Instructions**: Use `REACT_APP_CLAUDE_INSTRUCTIONS` to tailor briefing style (e.g., "Focus on tech news, be concise"). +- **Data Sources**: Reddit JSON endpoints (`/r/subreddit.json`) and Hacker News (`topstories.json`) work well. RSS feeds are also supported. +- **Clear Cache**: Use the trash icon button to clear all cached data and reset the app. + +## License + +MIT License - see [LICENSE](LICENSE) file for details.