A full-stack, production-ready finance dashboard with real-time data visualization,
intelligent transaction categorization, and goal tracking.
Features · Tech Stack · Quick Start · API Docs · Deploy
| Feature | Description |
|---|---|
| 📊 Interactive Dashboard | Real-time charts for cash flow analysis, expense breakdowns, and investment tracking powered by Recharts |
| 🏷️ Smart Categorization | ML-ready keyword-based transaction categorization via a dedicated FastAPI microservice |
| 🎯 Goal Tracking | Set financial goals with a built-in monthly savings calculator and visual progress indicators |
| 📥 CSV Import / Export | Bulk import transactions from CSV files and export data for external analysis |
| 🔐 Auth0 Authentication | Enterprise-grade authentication with JWT validation, httpOnly cookie sessions, and demo mode for UAT |
| 🐳 Docker-Ready | One-command local development stack with Docker Compose |
| 🚀 CI/CD Pipeline | Automated builds and linting via GitHub Actions |
App Router · Server state caching · Composable charts · Fluid animations
-000000?style=flat-square&logo=jsonwebtokens&logoColor=white){kind=icon}
REST API · ORM migrations · Schema validation · Security hardened
Keyword categorization · ML-ready architecture · Hot reload
Monorepo · Containerized · CI/CD · Linted & formatted
findash/
├── apps/
│ ├── web/ # Next.js frontend (App Router)
│ │ ├── app/ # Routes, API routes, components
│ │ ├── public/ # Static assets
│ │ └── package.json
│ ├── api/ # Express REST API
│ │ ├── src/ # Routes, middleware, server entry
│ │ ├── prisma/ # Schema, migrations, seed
│ │ └── package.json
│ └── ml-api/ # FastAPI microservice (ML-ready)
│ ├── app/ # Application modules
│ └── requirements.txt
├── packages/
│ └── types/ # Shared TypeScript type definitions
├── .github/workflows/ # CI pipeline configuration
├── docker-compose.yml # Local development stack
├── DEPLOYMENT.md # Production deployment guide
├── .env.example # Environment variable template
├── tsconfig.base.json # Base TypeScript configuration
└── package.json # Workspace root
# 1. Clone the repository
git clone https://github.com/usmanrasheeddev/FinDash.git
cd FinDash
# 2. Install all workspace dependencies
npm install
# 3. Start PostgreSQL via Docker
docker compose up -d db
# 4. Configure environment
cp .env.example .env
cp apps/api/.env.example apps/api/.env # if exists
# 5. Run database migrations & seed
cd apps/api && npx prisma migrate dev --name init && cd ../..
npm run seed --workspace @findash/api
# 6. Start development servers
npm run dev --workspace @findash/api # API → http://localhost:4000
npm run dev --workspace @findash/web # Web → http://localhost:3000Tip
To start the optional ML service, run docker compose up -d ml-api
Spin up the entire application with a single command:
docker compose up -dThis starts PostgreSQL, the Express API, the Next.js frontend, and the FastAPI ML service.
Copy .env.example to .env at the project root and configure:
| Variable | Service | Description |
|---|---|---|
DATABASE_URL |
 |
PostgreSQL connection string |
NEXT_PUBLIC_API_URL |
 |
API base URL (default: http://localhost:4000) |
NEXT_PUBLIC_AUTH0_DOMAIN |
|
Auth0 tenant domain |
NEXT_PUBLIC_AUTH0_CLIENT_ID |
|
Auth0 application client ID |
AUTH0_CLIENT_SECRET |
|
Auth0 application secret |
NEXT_PUBLIC_AUTH0_AUDIENCE |
|
Auth0 API identifier |
AUTH0_ISSUER |
|
Auth0 issuer URL for JWT validation |
AUTH0_AUDIENCE |
|
Auth0 API audience for JWT validation |
ML_SERVICE_URL |
|
ML microservice URL (default: http://localhost:8000) |
ALLOW_DEMO |
|
Enable demo mode without JWT (UAT only) |
CORS_ORIGIN |
|
Allowed frontend origin in production |
FinDash uses 
- Login Flow: Users authenticate via the header login button → tokens stored in httpOnly cookies → forwarded to the API through an internal proxy at
/api/proxy/* - Demo Mode: If Auth0 is not configured, the app operates with a demo user for local development
- Production: The API requires valid JWTs for all non-public routes. Set
ALLOW_DEMO=truetemporarily during UAT, then disable for production
| Setting | Value |
|---|---|
| Application Type | Regular Web Application |
| Callback URLs | https://<your-domain>/api/auth/callback |
| Logout URLs | https://<your-domain>/ |
| Web Origins | https://<your-domain> |
Base URL:
http://localhost:4000
| Method | Endpoint | Description |
|---|---|---|
 |
/health |
Service health check |
|
/config |
Non-sensitive readiness info |
|
/transactions |
List all transactions |
 |
/transactions |
Create a transaction |
|
/goals |
List all goals |
|
/goals |
Create a goal |
|
/data/import |
Import transactions from CSV (multipart) |
|
/data/export |
Export transactions as CSV |
|
/ml/categorize |
Categorize transactions via ML service |
📋 ML Categorize — Request Body
{
"items": [
{ "description": "Starbucks Coffee" },
{ "description": "Netflix Monthly" }
]
}FinDash is designed for modern cloud deployment:
| Service | Platform | Directory |
|---|---|---|
| Frontend |  |
apps/web |
| API + Database |  |
apps/api |
| ML Service |  |
apps/ml-api |
Note
See DEPLOYMENT.md for detailed step-by-step deployment instructions, required environment variables, and troubleshooting tips.
# Run linting across all workspaces
npm run lint
# Format code with Prettier
npm run format
# Run tests
npm run test
# Build all workspaces
npm run build- Auth0 integration (Web + API JWT validation)
- Interactive dashboard charts (cash flow, expenses, investments)
- Transactions CRUD with CSV import flow
- Goal tracking with monthly savings calculator
- Unit & E2E test coverage expansion
- Real ML model integration for smart categorization
- Budget alerts & notifications
- Mobile-responsive PWA support
- Multi-currency support
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is open source and available under the MIT License.
Built with ❤️ by Usman Rasheed
