Tax-aware portfolio analysis tool that turns messy brokerage statements and portfolio exports into actionable, tax-smart insights. Privacy-focused architecture with secure file handling and guest-first experience.
🔗 Live at taxrebalancer.com
| Problem | How TaxRebalancer Solves It |
|---|---|
| Tax-aware rebalancing is hard — translating holdings to a tax-smart plan without spreadsheets | Dedicated harvest algorithm that computes tax-optimal sell sequences with ST/LT classification |
| Brokerage exports are messy — PDFs/CSVs/Excel with inconsistent formats | Secure upload pipeline with format detection and validation (PDF statements, Excel/CSV/JSON portfolios) |
| Privacy concerns — users worry about sensitive financial data | Signed URL uploads with time-limited access, strict validation, no permanent server storage of raw files |
| Onboarding friction — requiring signup kills conversion | Guest mode with admin-configurable limits—try before creating an account |
| Multi-portfolio management — needs access controls | Ownership rules and portfolio service layer with user-scoped access |
- Harvest Algorithm — Tax-lot selection with FIFO or tax-optimized ordering
- ST/LT Classification — Gain/loss categorization based on holding period
- Cross-Offset Calculation — Net short-term losses against long-term gains (and vice versa)
- Tax Budget Enforcement — Stop selling when max tax budget reached
- Raise Cash Mode — Liquidate positions to raise a target amount
- Signed URL Uploads — Backend requests time-limited signed URLs via Cloud Functions
- XHR PUT with Progress — Direct upload to cloud storage with progress tracking
- Strict Validation — PDF statements (≤25MB), portfolio files (Excel/CSV/JSON ≤10MB)
- PII Redaction — Built-in service for sensitive data removal
- Try Before Signup — Full functionality with guest limits
- Admin-Configurable — Guest portfolio limits, rebalance counts controlled via admin panel
- Seamless Upgrade — Guest data persists to localStorage, can be migrated on registration
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS |
| State | React Context (Auth, Guest, Parser, Admin) |
| Auth | Firebase Authentication |
| Database | Cloud Firestore |
| Functions | Firebase Cloud Functions (signed URLs, parsing) |
| Hosting | Firebase Hosting |
┌─────────────────────────────────────────────────────────────┐
│ REACT FRONTEND │
│ Home │ Dashboard │ GuestDashboard │ Analysis │ Admin │
└────────────────────────────┬────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────┐
│ CONTEXT PROVIDERS │
│ AuthContext │ GuestContext │ ParserContext │ AdminContext │
└────────────────────────────┬────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────┐
│ FIREBASE SERVICES │
│ Auth │ Firestore │ Cloud Functions │ Storage │
└────────────────────────────┬────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────┐
│ SIGNED URL UPLOAD FLOW │
│ getSignedUploadUrl() → XHR PUT → Progress → Validation │
└─────────────────────────────────────────────────────────────┘
The harvest algorithm (src/lib/harvestAlgorithm.js) implements:
// Input
{
previewRows, // Portfolio holdings with lots
securities, // Security metadata
longTermRate, // Tax rate for LT gains
shortTermRate, // Tax rate for ST gains
dispositionMethod, // 'default' (tax-optimized) or 'fifo'
maxTaxBudget, // Stop when budget exhausted
raiseCash, // Target cash to raise
}
// Output
{
proposedTrades, // Which lots to sell
stGain, stLoss, // Short-term totals
ltGain, ltLoss, // Long-term totals
estimatedTax, // Projected tax liability
cashRaised, // Total cash generated
}Tax Lot Selection Logic:
- Default Mode — Sell losses first (prefer LT), then gains (prefer LT)
- FIFO Mode — Sell strictly by trade date
- Cross-Offset — Net ST losses against LT gains to minimize tax
- Budget Enforcement — Stop when cumulative tax exceeds budget
┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Client │───▶│ Cloud Function │───▶│ Cloud Storage │
│ (Browser) │ │ getSignedUploadUrl│ │ (Signed PUT) │
└─────────────┘ └──────────────────┘ └─────────────────┘
│ │
│ 1. Request URL │
│───────────────────▶│
│ │
│ 2. Signed URL + │
│ expiration │
│◀───────────────────│
│ │
│ 3. XHR PUT with │
│ progress │
│─────────────────────────────────────▶│
Validation Rules:
- Statement PDFs:
application/pdf, max 25MB - Portfolio files: Excel/CSV/JSON, max 10MB
- Content-Type verification
- Size limits enforced client + server side
# Clone and install
git clone https://github.com/Mitzseen/portfolio-rebalancer.git
cd portfolio-rebalancer
npm install
# Set up Firebase
cp .env.example .env
# Add your Firebase config keys
# Run development server
npm run devportfolio-rebalancer/
├── src/
│ ├── components/
│ │ ├── ui/ # Reusable primitives
│ │ ├── SecureFileUploadModal.jsx # Upload with validation
│ │ └── PortfolioAnalysis.jsx # Results display
│ ├── contexts/
│ │ ├── AuthContext.jsx # Firebase auth state
│ │ ├── GuestContext.jsx # Guest user management
│ │ ├── ParserContext.jsx # File parsing state
│ │ └── AdminContext.jsx # Admin settings
│ ├── hooks/
│ │ ├── useDataParser.jsx # PDF/Excel parsing
│ │ └── useStreamingUpload.jsx # Progress tracking
│ ├── lib/
│ │ ├── harvestAlgorithm.js # Core rebalancing engine
│ │ ├── signedUploadService.js # Signed URL flow
│ │ ├── piiRedactionService.js # Sensitive data removal
│ │ └── firebase.js # Firebase config
│ └── pages/
│ ├── GuestDashboard.jsx # Guest experience
│ ├── Dashboard.jsx # Registered user
│ └── Analysis.jsx # Results page
├── functions/
│ └── src/
│ ├── index.ts # Cloud Function exports
│ └── parserEngine.ts # PDF/Excel parsing
└── public/
└── assets/ # Static images
| Decision | Rationale |
|---|---|
| Signed URL uploads | Safer than direct uploads, time-limited access, scales better |
| Guest mode first | Reduce friction, let users validate value before commitment |
| Admin-configurable limits | Business flexibility without code deploys |
| Harvest algorithm isolated | Clean separation of tax logic from UI concerns |
| Educational approach | Explain why each trade is recommended |
- Built a tax-aware portfolio analysis tool with React + Firebase supporting PDF/Excel statement uploads and tax-optimized trade recommendations
- Implemented signed URL upload pipeline via Cloud Functions for secure, time-limited file handling with progress tracking
- Designed guest vs registered user flow with admin-configurable limits to reduce onboarding friction
- Built harvest algorithm implementing tax-lot selection with ST/LT classification, cross-offset calculations, and budget enforcement
- Architected context-based state management separating auth, guest, parser, and admin concerns for maintainability
Proprietary — All Rights Reserved
This software is proprietary and actively used in a commercial product at taxrebalancer.com. You may view the source code for educational purposes only. See LICENSE for full terms.
Built by a FINRA-licensed engineer (Series 7/63) who understands both the finance domain and the engineering required to ship reliable software.