{"id":35066659,"url":"https://github.com/jbrannigan/portfoliotracker","last_synced_at":"2026-04-13T15:33:54.793Z","repository":{"id":329505811,"uuid":"1119853915","full_name":"jbrannigan/portfoliotracker","owner":"jbrannigan","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-23T15:54:53.000Z","size":425,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-31T17:18:29.971Z","etag":null,"topics":["express","finance","investments","portfolio","pwa","react","sqlite","trading","typescript","vite"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbrannigan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-20T01:12:55.000Z","updated_at":"2025-12-23T15:54:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jbrannigan/portfoliotracker","commit_stats":null,"previous_names":["jbrannigan/portfoliotracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jbrannigan/portfoliotracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbrannigan%2Fportfoliotracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbrannigan%2Fportfoliotracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbrannigan%2Fportfoliotracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbrannigan%2Fportfoliotracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbrannigan","download_url":"https://codeload.github.com/jbrannigan/portfoliotracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbrannigan%2Fportfoliotracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31759529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","finance","investments","portfolio","pwa","react","sqlite","trading","typescript","vite"],"created_at":"2025-12-27T11:31:41.877Z","updated_at":"2026-04-13T15:33:54.766Z","avatar_url":"https://github.com/jbrannigan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Portfolio Tracker PWA\n\nA local-first Progressive Web App for tracking investment positions across multiple brokerage accounts and watchlists, with consolidated ratings from Motley Fool and Seeking Alpha services.\n\n**Current Status:** Backend 100% Complete | Frontend 95% Complete | All Features Live\n\n📊 See [docs/PROGRESS.md](./docs/PROGRESS.md) for detailed implementation status\n✅ See [docs/CHECKLIST_STATUS.md](./docs/CHECKLIST_STATUS.md) for phase-by-phase completion\n\n## Screenshots\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/dashboard.png\" alt=\"Dashboard\" width=\"800\"/\u003e\n\u003c/p\u003e\n\n*Dashboard view with portfolio summary, TradingView heatmaps, and quick stats*\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/position-detail.png\" alt=\"Position Detail\" width=\"800\"/\u003e\n\u003c/p\u003e\n\n*Position detail page with TradingView charts, ratings from Seeking Alpha and Motley Fool*\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/positions-list.png\" alt=\"Positions List\" width=\"800\"/\u003e\n\u003c/p\u003e\n\n*Positions list with sector and watchlist information*\n\n## Project Overview\n\nThis application enables an investor to:\n- Track actual positions across multiple Schwab brokerage accounts\n- Manage watchlists from subscription services (Motley Fool, Seeking Alpha)\n- Calculate target allocations based on equal-weighting within watchlists\n- View consolidated ratings from multiple sources on a single position summary page\n- Log buy/sell transactions with reasons and article references\n- Get live quotes and performance stats via Alpha Vantage API\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        iPad (Primary)                          │\n│                      PWA - React + Vite                        │\n│                                                                 │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │\n│  │  Position   │  │  Watchlist  │  │    Transaction Log      │ │\n│  │  Summary    │  │  Manager    │  │    + Export             │ │\n│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              │ Home Network (HTTP)\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                    MacBook (Local Server)                       │\n│                      Node.js + Express                          │\n│                                                                 │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │\n│  │  API Proxy  │  │   SQLite    │  │   Import/Export         │ │\n│  │  (Alpha V.) │  │   Database  │  │   CSV/Excel Handlers    │ │\n│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              │ HTTPS (outbound only)\n                              ▼\n                    ┌─────────────────┐\n                    │  Alpha Vantage  │\n                    │      API        │\n                    └─────────────────┘\n```\n\n## Key Features\n\n### 1. Position Summary Page (Per Symbol)\n- **Merged ratings view**: Motley Fool + Seeking Alpha side-by-side\n- **Account positions**: Shows shares held in each account + total\n- **Watchlist membership**: Which watchlists include this symbol\n- **Target vs Actual**: Per-watchlist target allocation vs actual holdings\n- **Quick links**: Seeking Alpha page, Motley Fool page\n- **Live data**: Current price, day change, performance metrics (from Alpha Vantage)\n\n### 2. Watchlist Management\n- Import watchlists from Seeking Alpha Excel exports\n- Import scorecards from Motley Fool CSV exports\n- Assign dollar allocation per watchlist (e.g., \"$50,000 for Alpha Picks\")\n- Auto-calculate equal-weight target per position\n\n### 3. Account Management\n- Import positions from Schwab CSV exports\n- Support multiple accounts with distinct names\n- Track actual shares per symbol per account\n- Aggregate positions across accounts\n\n### 4. Transaction Log\n- Log buys and sells with date, symbol, shares, price, account\n- Structured reasons: \"Added to watchlist\", \"Dropped from watchlist\", \"Rebalance\"\n- Free-form notes and article links\n- Export to CSV or Excel\n\n### 5. Position Tracking \u0026 Status Badges\n- **Watchlist-position links**: Track which watchlist recommendations led to purchases\n- **Status badges**: Visual indicators for actionable positions\n  - **BUY**: Watchlist recommends symbol but no position held\n  - **BUY MORE**: Position is \u003e10% underweight vs target allocation\n  - **SELL SOME**: Position is \u003e10% overweight vs target allocation\n  - **DROPPED**: Watchlist dropped the recommendation but you still hold shares\n- **Needs Attention dashboard**: Highlights positions requiring action\n- **Status filters**: Filter position list by status (All, Needs Action, Dropped, On Target)\n\n### 6. Dashboard / Overview\n- Portfolio summary by account\n- Performance by watchlist\n- Needs Attention section with actionable items\n- Positions needing rebalancing (actual vs target)\n- Recent transactions\n\n## Documentation\n\n- **[Data Model](./docs/DATA_MODEL.md)** - Database schema and relationships\n- **[Import Formats](./docs/IMPORT_FORMATS.md)** - CSV/Excel parsing specifications\n- **[API Specification](./docs/API_SPEC.md)** - REST API endpoints and payloads\n- **[UI Specification](./docs/UI_SPEC.md)** - Page layouts and component specs\n- **[Setup Guide](./docs/SETUP.md)** - Detailed environment setup instructions\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+ and npm\n- SQLite 3\n- (Optional) Alpha Vantage API key for live quotes\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/portfoliotracker.git\ncd portfoliotracker\n\n# Install dependencies\nnpm install\n\n# Copy environment template\ncp .env.example .env\n\n# Edit .env and add your Alpha Vantage API key (optional)\n# ALPHA_VANTAGE_API_KEY=your_key_here\n```\n\n### Running the Application\n\n```bash\n# Start both server and client in development mode\nnpm run dev\n```\n\n**Access Points:**\n- **Client (Dashboard):** http://localhost:5173\n- **Server API:** http://localhost:3001\n- **API Health:** http://localhost:3001/api/health\n\n**Network Access (for iPad/mobile):**\n- Find your local IP in the Vite startup output\n- Access from other devices: http://YOUR_LOCAL_IP:5173\n\n### What's Working Now\n\n✅ **Backend (100% Complete):**\n- REST API with 20+ endpoints\n- SQLite database with position-watchlist tracking\n- Schwab, Seeking Alpha \u0026 Motley Fool imports\n- Alpha Vantage integration with rate limiting\n- Transaction logging with CSV/Excel export\n- Dashboard needs-attention API\n\n✅ **Frontend (95% Complete):**\n- Full dashboard with portfolio summary and needs attention section\n- Position list with status badges and filtering\n- Position detail with TradingView charts and watchlist status\n- Watchlist management with allocation targets\n- Account management with cascade delete\n- Transaction log with export options\n- Import wizard for all file types\n- Admin page for database maintenance\n- PWA with offline indicator\n\n### Testing the API\n\n```bash\n# List all symbols\ncurl http://localhost:3001/api/symbols | jq .\n\n# Get recent transactions\ncurl http://localhost:3001/api/transactions/recent | jq .\n\n# Import Schwab CSV\ncurl -X POST http://localhost:3001/api/import/schwab \\\n  -F \"file=@/Users/jimbrannigan/Public/Jim's Roth IRA-Positions-2025-12-17-164125.csv\"\n\n# Export transactions to CSV\ncurl \"http://localhost:3001/api/transactions/export/csv\" \u003e transactions.csv\n```\n\n### Database Access\n\nThe SQLite database is automatically created at `./data/portfolio.db` on first run.\n\n```bash\n# Access the database\nsqlite3 ./data/portfolio.db\n\n# View tables\n.tables\n\n# Query examples\nSELECT * FROM symbols LIMIT 5;\nSELECT * FROM accounts;\nSELECT * FROM positions;\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## Acknowledgments\n\n- [TradingView](https://www.tradingview.com/) for embeddable financial charts\n- [Alpha Vantage](https://www.alphavantage.co/) for market data API\n- [shadcn/ui](https://ui.shadcn.com/) for React UI components\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbrannigan%2Fportfoliotracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbrannigan%2Fportfoliotracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbrannigan%2Fportfoliotracker/lists"}