{"id":42075240,"url":"https://github.com/xmljim/retirement-simulator","last_synced_at":"2026-01-26T09:20:55.395Z","repository":{"id":331033008,"uuid":"1122393532","full_name":"xmljim/retirement-simulator","owner":"xmljim","description":"A comprehensive retirement portfolio simulation tool for modeling accumulation and distribution phases of retirement savings","archived":false,"fork":false,"pushed_at":"2025-12-31T20:49:58.000Z","size":1049,"stargazers_count":0,"open_issues_count":90,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-02T06:18:57.212Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xmljim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"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-24T16:23:30.000Z","updated_at":"2025-12-25T22:48:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xmljim/retirement-simulator","commit_stats":null,"previous_names":["xmljim/retirement-simulator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/xmljim/retirement-simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmljim%2Fretirement-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmljim%2Fretirement-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmljim%2Fretirement-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmljim%2Fretirement-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xmljim","download_url":"https://codeload.github.com/xmljim/retirement-simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmljim%2Fretirement-simulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28772733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T08:38:24.014Z","status":"ssl_error","status_checked_at":"2026-01-26T08:38:22.080Z","response_time":59,"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":[],"created_at":"2026-01-26T09:20:54.621Z","updated_at":"2026-01-26T09:20:55.390Z","avatar_url":"https://github.com/xmljim.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Retirement Portfolio Simulator\n\n[![CI](https://github.com/xmljim/retirement-simulator/actions/workflows/ci.yml/badge.svg)](https://github.com/xmljim/retirement-simulator/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/xmljim/retirement-simulator/branch/main/graph/badge.svg)](https://codecov.io/gh/xmljim/retirement-simulator)\n\nA comprehensive retirement portfolio simulation tool that models the accumulation and distribution phases of retirement savings, enabling users to project portfolio performance under various scenarios.\n\n## Overview\n\nRetirement planning requires understanding how multiple variables interact over time:\n\n- Contribution rates and employer matching\n- Investment returns (varying pre/post retirement)\n- Inflation and cost-of-living adjustments\n- Social Security timing and amounts\n- Pension and annuity income\n- Withdrawal strategies and rates\n\nThis tool models these interactions on a monthly basis, providing visibility into portfolio balance trajectories from the present through retirement.\n\n## Features\n\n### Core Capabilities\n\n- **Multi-Account Portfolio Support** - 401(k), IRA, Roth IRA, Roth 401(k), HSA, taxable brokerage\n- **IRS Contribution Rules** - Limits, catch-up contributions, SECURE 2.0 compliance\n- **Income Modeling** - Salary, Social Security, pensions, annuities, other sources\n- **Expense Budgeting** - Category-based with differentiated inflation rates\n- **Distribution Strategies** - Static (4% rule), Bucket, Spending Curve, Guardrails\n\n### Simulation Modes\n\n- **Deterministic** - Fixed return rates for baseline planning\n- **Monte Carlo** - Probabilistic analysis with configurable runs\n- **Historical Backtesting** - Test against actual market history\n\n### Analysis \u0026 Reporting\n\n- Portfolio timeline visualization\n- Cash flow analysis\n- Tax projections\n- Scenario comparison\n- Export to CSV, JSON, PDF\n\n## Quick Start\n\n### Prerequisites\n\n- Java 25 or higher\n- Maven 3.9+\n\n### Build\n\n```bash\nmvn clean install\n```\n\n### Run Tests\n\n```bash\nmvn test\n```\n\n### Run with Coverage\n\n```bash\nmvn verify\n```\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Project Goals](requirements/PROJECT_GOALS.md) | Vision, requirements, and milestones |\n| [Architecture](docs/ARCHITECTURE.md) | System design and package structure |\n| [Code Style](docs/CODE_STYLE.md) | Java coding standards and conventions |\n| [Testing](docs/TESTING.md) | Testing requirements and best practices |\n| [Contributing](docs/CONTRIBUTING.md) | How to contribute to the project |\n\n## Project Structure\n\n```\nretirement-simulator/\n├── src/\n│   ├── main/java/           # Application source code\n│   └── test/java/           # Test source code\n├── docs/                    # Development documentation\n│   ├── ARCHITECTURE.md\n│   ├── CODE_STYLE.md\n│   ├── CONTRIBUTING.md\n│   └── TESTING.md\n├── requirements/            # Project requirements\n│   └── PROJECT_GOALS.md\n└── pom.xml                  # Maven configuration\n```\n\n## Technology Stack\n\n- **Core Library**: Java 25\n- **Build Tool**: Maven\n- **Testing**: JUnit 5, AssertJ, Mockito\n- **API Layer**: Spring Boot (planned)\n- **UI**: React (planned)\n- **PDF Generation**: Apache PDFBox (planned)\n\n## Development\n\n### Branch Strategy\n\n- `main` - Production-ready code\n- `develop` - Integration branch\n- `feature/\u003cissue\u003e-\u003cdesc\u003e` - Feature development\n- `bugfix/\u003cissue\u003e-\u003cdesc\u003e` - Bug fixes\n\n### Quality Gates\n\nAll code must pass:\n\n- Checkstyle (code style)\n- SpotBugs (static analysis)\n- PMD (code smells)\n- JaCoCo (80% line coverage minimum)\n\n### Making Changes\n\n1. Create a feature branch from `develop`\n2. Make changes following [Code Style](docs/CODE_STYLE.md)\n3. Write tests following [Testing Standards](docs/TESTING.md)\n4. Submit a pull request\n\nSee [Contributing](docs/CONTRIBUTING.md) for detailed guidelines.\n\n## Roadmap\n\n| Milestone | Description | Status |\n|-----------|-------------|--------|\n| M0 | Project Setup \u0026 CI/CD | Complete |\n| M1 | Domain Model Foundation | Planned |\n| M2 | Core Transaction \u0026 Account Operations | Planned |\n| M3 | Multi-Account Portfolio \u0026 Contribution Rules | Planned |\n| M4 | Income Modeling | Planned |\n| M5 | Expense \u0026 Budget Modeling | Planned |\n| M6 | Distribution Strategies | Planned |\n| M7 | Simulation Engine | Planned |\n| M8 | Scenario Analysis | Planned |\n| M9 | Output \u0026 Reporting | Planned |\n| M10 | API Layer | Planned |\n| M11 | UI (React) | Planned |\n\nSee [Project Goals](requirements/PROJECT_GOALS.md) for detailed milestone breakdowns.\n\n## License\n\n[TBD]\n\n## Contact\n\n[TBD]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmljim%2Fretirement-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxmljim%2Fretirement-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmljim%2Fretirement-simulator/lists"}