initiate

CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md - Gmail Inbox Analyzer Project Guide
+
+## Project Overview
+This is a **Gmail Inbox Analyzer** - a Go application that fetches email metadata (sender, subject, date, message ID) from a Gmail inbox using the Gmail API. The tool outputs data in CSV or JSON format for organization and analysis purposes.
+
+## Architecture & Structure
+- **Single binary application** (`main.go`) - no complex module structure
+- **OAuth2 authentication** with Google's Gmail API
+- **Command-line interface** with three required arguments
+- **Two output formats**: CSV and JSON
+- **No persistent storage** - credentials are not stored locally
+
+## Key Files
+- `/Users/orejav/repos/mail-automation/main.go` - Main application code (155 lines)
+- `/Users/orejav/repos/mail-automation/go.mod` - Go module definition with Gmail API dependencies
+- `/Users/orejav/repos/mail-automation/go.sum` - Dependency checksums
+- `/Users/orejav/repos/mail-automation/README.md` - User documentation and setup instructions
+
+## Dependencies & Tech Stack
+- **Go 1.21** (minimum version)
+- **golang.org/x/oauth2** - OAuth2 authentication
+- **google.golang.org/api/gmail/v1** - Gmail API client
+- Standard library: `encoding/csv`, `encoding/json`, `net/http`, `context`
+
+## Development Commands
+```bash
+# Install/update dependencies
+go mod tidy
+
+# Run the application (requires Google OAuth credentials)
+go run main.go <CLIENT_ID> <CLIENT_SECRET> <csv|json>
+
+# Example usage
+go run main.go "123456789-abc.apps.googleusercontent.com" "GOCSPX-your_secret" csv > emails.csv
+go run main.go "123456789-abc.apps.googleusercontent.com" "GOCSPX-your_secret" json > emails.json
+
+# Build binary
+go build -o gmail-analyzer main.go
+```
+
+## Authentication Flow
+1. Application generates OAuth2 URL for Gmail readonly access
+2. User visits URL in browser and authorizes access
+3. User copies authorization code from browser
+4. User pastes code into terminal
+5. Application exchanges code for access token
+6. Token is used for API calls (not persisted)
+
+## Core Components
+1. **`main()`** - CLI argument parsing and orchestration
+2. **`getClient()`** - OAuth2 authentication flow
+3. **`fetchEmails()`** - Gmail API pagination and message retrieval
+4. **`parseMessage()`** - Extract metadata from Gmail message headers
+5. **`outputCSV()`** / **`outputJSON()`** - Data formatting and output
+
+## Data Structure
+```go
+type EmailInfo struct {
+    Sender  string `json:"sender"`
+    Subject string `json:"subject"`
+    Date    string `json:"date"`
+    ID      string `json:"id"`
+}
+```
+
+## Google Cloud Setup Required
+- Google Cloud Console project
+- Gmail API enabled
+- OAuth 2.0 Client ID (Desktop application type)
+- Client ID and Client Secret credentials
+
+## API Limitations & Behavior
+- Uses Gmail API readonly scope: `gmail.GmailReadonlyScope`
+- Fetches emails from inbox only (`in:inbox` query)
+- Processes all emails with pagination (no date/count limits)
+- Rate limiting handled by Google's client library
+- No email content/body is fetched - headers only
+
+## Common Tasks for Claude
+1. **Modify output format** - Edit `outputCSV()` or `outputJSON()` functions
+2. **Add filtering** - Modify Gmail query in `fetchEmails()` function
+3. **Add new metadata fields** - Update `EmailInfo` struct and `parseMessage()`
+4. **Error handling improvements** - Add retry logic or better error messages
+5. **Configuration** - Add config file support or environment variables
+6. **Batch processing** - Add date range or count limits
+
+## Testing & Debugging
+- No unit tests currently exist
+- Manual testing requires valid Google OAuth credentials
+- Debug by checking Gmail API quotas in Google Cloud Console
+- Common issues: invalid credentials, API not enabled, rate limiting
+
+## Security Considerations
+- OAuth credentials passed as command-line arguments (visible in process list)
+- No credential persistence (security by design)
+- Readonly Gmail access only
+- Consider environment variables for credentials in production use
+
+## Extension Points
+- Add support for other Gmail folders/labels
+- Implement credential caching (with proper security)
+- Add filtering by date range, sender, or subject patterns
+- Export to other formats (Excel, database)
+- Add email content analysis capabilities