Argus is a full-stack financial simulation engine that stress-tests startup strategies across four parallel 3-year timelines — Baseline, Expected, Best Case, and Worst Case. Founders input their financial assumptions, layer in business decisions like hiring or marketing, and get back a resilience grade, runway forecast, and automated mitigation strategies — all behind a secure, per-user account.
Design reference: Figma — App Design
- Problem Statement
- Solution Overview
- Tech Stack
- Project Structure
- Prerequisites
- Getting Started
- API Endpoints
- Frontend Pages
- Environment Variables
- Docker Compose
- UI Previews
- Future Scope
- References
- Attributions
Most early-stage startups rely on static spreadsheets that fail to account for optimism bias or the compounding impact of individual business decisions. When a marketing campaign underperforms or a hiring plan runs over budget, founders have no way to anticipate the downstream effect on cash flow — leading to unexpected runway exhaustion and avoidable failure.
Argus replaces single-path projections with parallel 36-month simulations. Business events like hiring, marketing, and expansion are applied with standardized cost and timing assumptions across every scenario, removing guesswork. The engine then returns a resilience grade and risk signals so founders can see the consequences of a decision before committing capital.
- Multi-Scenario Branching: simultaneously generates four parallel 36-month financial timelines (Baseline, Expected, Best Case, Worst Case) to evaluate varying risk levels
- Event Simulation Engine: mathematically calculates the impact of business events such as marketing campaigns, hiring, and capital expansion on the overall financial ledger
- Standardized Event Assumptions: applies consistent backend-defined assumptions for event timing, cash burn, delayed revenue impact, and scenario branching to reduce optimism bias
- Resilience Scoring: computes a standardized resilience grade (O / A / B / C / F) from simulated cash behaviour, including runway duration, insolvency timing, and cash stability
- Automated Mitigation Strategies: surfaces actionable recovery recommendations when risk signals such as critical runway or sustained negative cash flow are detected
- Interactive Dashboard: dynamic charts track cash balances, net income, and revenue trajectories across all simulated timelines with side-by-side scenario comparison
- Secure Per-User Accounts: JWT-based authentication ensures each founder's scenarios and simulation history are private and persisted across sessions
| Layer | Technology |
|---|---|
| Frontend | React 18 · TypeScript · Vite 6 · Tailwind CSS 4 · Recharts · React Router 7 |
| Backend | Python 3 · FastAPI · SQLAlchemy · Alembic · Pydantic |
| Database | PostgreSQL 15 |
| Auth | JWT (PyJWT) · bcrypt (passlib) |
| Infra | Docker Compose |
Argus_Project/
├── src/ # Frontend source
│ ├── main.tsx # React entry point
│ ├── app/
│ │ ├── routes.ts # Client-side routing
│ │ ├── pages/ # Landing, Dashboard, Scenario Builder, Comparison
│ │ ├── components/ # Shared / layout components
│ │ └── services/ # API service layer
│ ├── imports/ # Shared UI primitives
│ └── styles/ # Global styles
│
├── startup_financial_engine/ # Backend source
│ ├── api.py # FastAPI application & routes
│ ├── auth.py # Password hashing & JWT helpers
│ ├── config.py # Environment / DB config
│ ├── database.py # SQLAlchemy engine & session
│ ├── main.py # Cash-flow metric calculations
│ ├── event_calculators.py # Event dispatcher for simulations
│ ├── resilience.py # Financial resilience grading logic (O, A, B, C, F)
│ ├── risk_signals.py # Runway and fragility detection
│ ├── mitigation_engine.py # Automated strategy generation
│ ├── year_simulator.py # Year-level simulation runner
│ ├── models/ # ORM & domain models
│ │ ├── user.py
│ │ ├── scenario.py
│ │ ├── scenario_decision.py
│ │ ├── simulation_run.py
│ │ ├── assumptions.py
│ │ ├── forecast.py
│ │ ├── year_simulator.py
│ │ ├── revenue.py / expenses.py / cashflow.py
│ │ ├── income_statement.py / balance_sheet.py
│ │ └── funding.py / decisions.py
│ ├── alembic/ # Database migrations
│ ├── requirements.txt
│ └── .env # DB connection string (git-ignored)
│
├── docker-compose.yml # App + PostgreSQL services
├── vite.config.ts # Vite dev server + API proxy
├── package.json
└── index.html
- Node.js ≥ 18 and npm
- Python ≥ 3.11
- PostgreSQL 15 (or use Docker Compose — see below)
git clone <repo-url>
cd Argus_ProjectOption A — Docker Compose (recommended)
docker compose up -d dbThis spins up PostgreSQL 15 on localhost:5432 with:
- Database:
argus_dev - User / Password:
postgres/postgres
Option B — Local PostgreSQL
Create the database manually and make sure the connection string in startup_financial_engine/.env matches:
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/argus_dev
cd startup_financial_engine
python -m venv venv
# Activate the virtual environment
# Windows (PowerShell)
.\venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
pip install -r requirements.txtRun database migrations:
alembic upgrade headStart the API server:
uvicorn api:app --reload --port 8000The API is now available at http://localhost:8000. Interactive docs at http://localhost:8000/docs.
# From the project root
npm install
npm run devVite starts at http://localhost:5173 and automatically proxies /api/* requests to the backend.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST |
/api/register |
— | Create a new user account |
POST |
/api/login |
— | Obtain a JWT access token |
POST |
/api/simulate |
🔒 | Run a 3-year financial simulation |
GET |
/api/simulation/latest |
🔒 | Get the latest simulation run |
GET |
/api/simulation-runs |
🔒 | List past simulation runs |
DELETE |
/api/simulation-runs/all |
🔒 | Delete all past simulation runs |
DELETE |
/api/simulation-runs/:id |
🔒 | Delete a specific simulation run |
GET |
/api/scenarios |
🔒 | List user's saved scenarios |
POST |
/api/scenarios |
🔒 | Create a new scenario with decisions |
GET |
/api/scenarios/:id |
🔒 | Get a single scenario |
PUT |
/api/scenarios/:id |
🔒 | Update a scenario |
DELETE |
/api/scenarios/:id |
🔒 | Delete a scenario |
POST |
/api/scenarios/decisions |
🔒 | Add a decision to the active scenario |
GET |
/api/scenarios/active/decisions |
🔒 | List decisions for the active scenario |
DELETE |
/api/scenarios/decisions/:id |
🔒 | Delete a specific scenario decision |
| Route | Page | Description |
|---|---|---|
/ |
Landing Page | Marketing / intro page |
/login |
Login | User authentication |
/signup |
Sign Up | New account registration |
/dashboard |
Financial Dashboard | Core simulation charts & metrics |
/dashboard/scenario-builder |
Scenario Builder | Create & edit what-if scenarios |
/dashboard/scenario-comparison |
Scenario Comparison | Compare scenario outcomes |
| Variable | Location | Default |
|---|---|---|
DATABASE_URL |
startup_financial_engine/.env |
postgresql://postgres:postgres@localhost:5432/argus_dev |
Note: The
.envfile is git-ignored. Copy the value above or set your own connection string.
To run both the app container and PostgreSQL together:
docker-compose up -dThe app container exposes port 8000 and automatically connects to the db service.
Input your starting cash, revenue, costs, and growth assumptions through the Financial Model Dashboard.
Layer in hiring, marketing, expansion, or other strategic moves using the Decision Library.
See how different scenarios affect your runway and cash position across the Baseline, Expected, Best Case, and Worst Case timelines.
Get resilience grades (O / A / B / C / F), insolvency risk signals, and actionable automated recommendations.
The system can be extended with an AI-driven advisory layer to provide insights, risk analysis, and strategic recommendations based on simulation outputs. This would enable natural language interaction and automated interpretation of financial results.
The platform can incorporate document processing capabilities to automatically extract financial assumptions from pitch decks, bank statements, and P&L sheets, reducing manual input.
Enhancements such as correlated Monte Carlo simulations can be introduced to model realistic dependencies between revenue and cost variables, improving prediction accuracy.
Exposing the simulation engine as a REST API would allow integration with third-party financial tools and services.
- UI components from shadcn/ui — MIT License
- Photos from Unsplash — Unsplash License
Drive Link: link