https://github.com/codernotme/finboard
Customizable Finance Dashboard where users can build their own real-time finance monitoring dashboard by connecting to various financial APIs and displaying real-time data through customizable widgets.
https://github.com/codernotme/finboard
Last synced: 5 months ago
JSON representation
Customizable Finance Dashboard where users can build their own real-time finance monitoring dashboard by connecting to various financial APIs and displaying real-time data through customizable widgets.
- Host: GitHub
- URL: https://github.com/codernotme/finboard
- Owner: codernotme
- Created: 2026-01-23T08:07:36.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-23T08:42:49.000Z (5 months ago)
- Last Synced: 2026-01-24T01:29:21.982Z (5 months ago)
- Language: TypeScript
- Size: 182 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 📊 FinBoard - Customizable Finance Dashboard
> A powerful, real-time finance monitoring dashboard that lets you track stocks, markets, and portfolios with fully customizable widgets.
---
## ✨ Features
### 🎯 Core Features
- **📈 Multiple Widget Types** - Tables, Finance Cards, and Interactive Charts
- **🎨 Drag & Drop Layout** - Rearrange your dashboard exactly how you want it
- **⚡ Real-time Data** - Live updates from financial APIs with configurable refresh intervals
- **🔧 Fully Customizable** - Configure every widget with custom titles, metrics, and display formats
- **💾 Auto-Save** - Your dashboard configuration persists across browser sessions
- **📱 Responsive Design** - Works seamlessly on desktop, tablet, and mobile devices
### 🚀 Advanced Features
- **🌓 Theme Switching** - Light and dark mode support
- **📊 Multiple Chart Types** - Candlestick and line charts with zoom capabilities
- **🔍 Smart Search & Filters** - Find and filter stocks instantly
- **💰 Custom Formatting** - Display data in multiple currencies and formats
- **📤 Export/Import** - Backup and share your dashboard configurations
- **⚡ Smart Caching** - Optimized API usage with intelligent data caching
---
## 🎬 Demo
🔗 **Live Demo**: [finboard-demo.vercel.app](https://finboard-demo.vercel.app) *(Coming soon)*
### Screenshots
| Dashboard View | Widget Configuration | Mobile Responsive |
|----------------|---------------------|-------------------|
|  |  |  |
---
## 🛠️ Tech Stack
### Frontend
- **Framework**: [Next.js 13+](https://nextjs.org/) with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS + shadcn/ui
- **State Management**: Redux Toolkit / Zustand
- **Charts**: Recharts
- **Drag & Drop**: dnd-kit
### APIs
- **Alpha Vantage** - Stock market data
- **Finnhub** - Real-time financial data
- Support for custom API integrations
### Deployment
- **Platform**: Vercel (recommended) / Netlify / AWS
- **CI/CD**: GitHub Actions
---
## 🚀 Getting Started
### Prerequisites
Make sure you have the following installed:
- **Node.js** 18+ ([Download](https://nodejs.org/))
- **npm** or **yarn** or **pnpm**
- **Git**
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/finboard.git
cd finboard
```
2. **Install dependencies**
```bash
npm install
# or
yarn install
# or
pnpm install
```
3. **Set up environment variables**
```bash
cp .env.example .env.local
```
Edit `.env.local` and add your API keys:
```env
NEXT_PUBLIC_ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key
NEXT_PUBLIC_FINNHUB_API_KEY=your_finnhub_key
```
4. **Install shadcn/ui components** (first time only)
```bash
# Initialize shadcn/ui
npx shadcn@latest init
# Install all required components
chmod +x scripts/install-shadcn.sh
./scripts/install-shadcn.sh
```
5. **Run the development server**
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```
6. **Open your browser**
Navigate to [http://localhost:3000](http://localhost:3000)
---
## 🔑 Getting API Keys
### Alpha Vantage (Free)
1. Visit [Alpha Vantage](https://www.alphavantage.co/support/#api-key)
2. Enter your email and get your free API key
3. **Limit**: 25 requests/day (free tier)
### Finnhub (Free)
1. Visit [Finnhub](https://finnhub.io/register)
2. Create a free account
3. Copy your API key from the dashboard
4. **Limit**: 60 calls/minute (free tier)
### Setting Up API Keys
**Option 1: Environment Variables** (Recommended)
```env
# .env.local
NEXT_PUBLIC_ALPHA_VANTAGE_API_KEY=YOUR_KEY_HERE
NEXT_PUBLIC_FINNHUB_API_KEY=YOUR_KEY_HERE
```
**Option 2: In-App Configuration**
1. Open FinBoard
2. Click Settings (⚙️) in the top right
3. Navigate to "API Keys" tab
4. Enter your API keys and save
---
## 📖 Usage Guide
### Creating Your First Widget
1. **Click "Add Widget"** button on the dashboard
2. **Select Widget Type**:
- **Table** - For viewing multiple stocks in a list
- **Finance Card** - For watchlists, gainers, or quick stats
- **Chart** - For price trends and technical analysis
3. **Configure the Widget**:
- Set a custom title
- Choose your API endpoint
- Select which data fields to display
- Set refresh interval
4. **Click "Create"** - Your widget appears instantly!
### Customizing Your Dashboard
**Rearranging Widgets**
- Simply **drag and drop** widgets to your preferred position
- Layout automatically saves
**Editing a Widget**
- Click the **settings icon** (⚙️) on any widget
- Modify title, data fields, or refresh settings
- Changes apply immediately
**Deleting a Widget**
- Click the **trash icon** (🗑️) on any widget
- Confirm deletion
- Widget removed instantly
### Widget Types Explained
#### 📊 Table Widget
Perfect for monitoring multiple stocks at once.
**Features**:
- Paginated view (10, 25, 50, 100 rows)
- Search across all columns
- Sort by any column
- Filter by price, volume, change %
**Example Use Cases**:
- Portfolio tracking
- Market screening
- Sector comparison
#### 💰 Finance Card Widget
Quick overview of specific market segments.
**Types**:
- **Watchlist** - Your favorite stocks
- **Market Gainers** - Top performers
- **Performance Data** - Portfolio stats
- **Financial Data** - Key metrics (P/E, Market Cap)
**Features**:
- Compact card view
- Color-coded gains/losses
- List or single card display
#### 📈 Chart Widget
Visualize price movements and trends.
**Chart Types**:
- **Candlestick** - OHLC data with volume
- **Line Chart** - Clean price trends
**Time Intervals**:
- Daily (intraday)
- Weekly
- Monthly
**Features**:
- Interactive tooltips
- Zoom and pan
- Date range selection
---
## 📁 Project Structure
```
finboard/
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── layout.tsx # Root layout
│ │ ├── page.tsx # Home page
│ │ ├── dashboard/ # Dashboard routes
│ │ └── api/ # API routes (proxy)
│ │
│ ├── components/ # React components
│ │ ├── widgets/ # Widget components
│ │ │ ├── TableWidget.tsx
│ │ │ ├── CardWidget.tsx
│ │ │ └── ChartWidget.tsx
│ │ ├── layout/ # Layout components
│ │ │ ├── Header.tsx
│ │ │ ├── Sidebar.tsx
│ │ │ └── DashboardGrid.tsx
│ │ ├── modals/ # Modal dialogs
│ │ │ ├── AddWidgetModal.tsx
│ │ │ └── WidgetConfigModal.tsx
│ │ ├── ui/ # shadcn/ui components
│ │ └── common/ # Shared components
│ │
│ ├── lib/ # Utilities and configs
│ │ ├── api/ # API clients
│ │ │ ├── alphaVantage.ts
│ │ │ └── finnhub.ts
│ │ ├── store/ # State management
│ │ │ ├── store.ts
│ │ │ ├── widgetSlice.ts
│ │ │ └── dashboardSlice.ts
│ │ ├── hooks/ # Custom React hooks
│ │ │ ├── useWidgets.ts
│ │ │ └── useApiData.ts
│ │ └── utils/ # Helper functions
│ │ ├── formatters.ts
│ │ ├── cache.ts
│ │ └── storage.ts
│ │
│ ├── types/ # TypeScript types
│ │ ├── widget.ts
│ │ ├── api.ts
│ │ └── dashboard.ts
│ │
│ ├── styles/ # Global styles
│ │ └── globals.css
│ │
│ └── config/ # Configuration files
│ ├── apiEndpoints.ts
│ └── constants.ts
│
├── public/ # Static assets
│ ├── images/
│ └── icons/
│
├── scripts/ # Utility scripts
│ └── install-shadcn.sh
│
├── docs/ # Documentation
│ ├── PRD.md
│ ├── SRS.md
│ └── API.md
│
├── .env.example # Environment variables template
├── .env.local # Local environment (gitignored)
├── next.config.js # Next.js configuration
├── tailwind.config.ts # Tailwind configuration
├── tsconfig.json # TypeScript configuration
├── package.json # Dependencies
└── README.md # This file
```
---
## 🎨 Customization
### Themes
FinBoard supports both light and dark themes:
```tsx
// Toggle theme programmatically
import { useTheme } from 'next-themes'
const { theme, setTheme } = useTheme()
// Switch theme
setTheme(theme === 'dark' ? 'light' : 'dark')
```
### Custom API Integration
Add your own financial data source:
```typescript
// src/lib/api/customAPI.ts
export const fetchCustomData = async (endpoint: string) => {
const response = await fetch(`https://your-api.com/${endpoint}`, {
headers: {
'Authorization': `Bearer ${process.env.NEXT_PUBLIC_CUSTOM_API_KEY}`
}
})
return response.json()
}
```
Register it in the widget configuration:
```typescript
// src/config/apiEndpoints.ts
export const API_PROVIDERS = {
'alpha-vantage': { /* ... */ },
'finnhub': { /* ... */ },
'custom': {
name: 'Custom API',
baseUrl: 'https://your-api.com',
endpoints: { /* ... */ }
}
}
```
---
## 🧪 Testing
### Run Tests
```bash
# Unit tests
npm run test
# E2E tests
npm run test:e2e
# Coverage report
npm run test:coverage
```
### Testing Strategy
- **Unit Tests**: Component logic and utilities
- **Integration Tests**: API integration and state management
- **E2E Tests**: Critical user flows (Playwright)
---
## 🚢 Deployment
### Deploy to Vercel (Recommended)
1. **Push to GitHub**
```bash
git add .
git commit -m "Initial commit"
git push origin main
```
2. **Import to Vercel**
- Go to [vercel.com](https://vercel.com)
- Click "New Project"
- Import your GitHub repository
- Add environment variables
- Click "Deploy"
3. **Add Environment Variables in Vercel**
- Go to Project Settings → Environment Variables
- Add `NEXT_PUBLIC_ALPHA_VANTAGE_API_KEY`
- Add `NEXT_PUBLIC_FINNHUB_API_KEY`
### Deploy to Netlify
```bash
# Install Netlify CLI
npm install -g netlify-cli
# Build the project
npm run build
# Deploy
netlify deploy --prod
```
### Deploy to AWS
See [AWS Deployment Guide](./docs/AWS_DEPLOYMENT.md) for detailed instructions.
---
## 📊 Performance Optimization
### Implemented Optimizations
- ✅ **Code Splitting** - Dynamic imports for widgets
- ✅ **Lazy Loading** - Components loaded on demand
- ✅ **Image Optimization** - Next.js Image component
- ✅ **API Caching** - Intelligent cache with TTL
- ✅ **Memoization** - React.memo for expensive components
- ✅ **Virtual Scrolling** - For large tables
### Performance Metrics
- **Initial Load**: < 3 seconds
- **Time to Interactive**: < 2 seconds
- **Lighthouse Score**: 90+
- **Bundle Size**: < 500KB (gzipped)
---
## 🤝 Contributing
We welcome contributions! Here's how you can help:
### How to Contribute
1. **Fork the repository**
2. **Create a feature branch**
```bash
git checkout -b feature/amazing-feature
```
3. **Make your changes**
4. **Commit with conventional commits**
```bash
git commit -m "feat: add amazing feature"
```
5. **Push to your fork**
```bash
git push origin feature/amazing-feature
```
6. **Open a Pull Request**
### Commit Convention
We use [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `style:` - Code style changes (formatting)
- `refactor:` - Code refactoring
- `test:` - Adding tests
- `chore:` - Maintenance tasks
### Code Style
- Follow the existing code style
- Run `npm run lint` before committing
- Add tests for new features
- Update documentation as needed
---
## 🐛 Troubleshooting
### Common Issues
**Problem**: API requests failing with CORS errors
**Solution**: Use Next.js API routes as proxy
```typescript
// src/app/api/proxy/route.ts
export async function GET(request: Request) {
const { searchParams } = new URL(request.url)
const endpoint = searchParams.get('endpoint')
const response = await fetch(`https://api.example.com/${endpoint}`)
const data = await response.json()
return Response.json(data)
}
```
**Problem**: Widgets not saving
**Solution**: Check browser storage is enabled and not full
```typescript
// Check localStorage availability
if (typeof window !== 'undefined' && window.localStorage) {
// Safe to use localStorage
}
```
**Problem**: API rate limit exceeded
**Solution**: Increase cache TTL or reduce refresh frequency
```typescript
// Adjust in widget settings
refreshInterval: 300000 // 5 minutes instead of 1 minute
```
**Problem**: Charts not rendering
**Solution**: Ensure data is in correct format
```typescript
// Expected format for Recharts
const data = [
{ date: '2024-01', value: 100 },
{ date: '2024-02', value: 120 }
]
```
### Need Help?
- 📖 [Documentation](./docs)
- 💬 [Discussions](https://github.com/yourusername/finboard/discussions)
- 🐛 [Report a Bug](https://github.com/yourusername/finboard/issues)
- ✨ [Request a Feature](https://github.com/yourusername/finboard/issues/new?template=feature_request.md)
---
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
- [Next.js](https://nextjs.org/) - The React framework
- [shadcn/ui](https://ui.shadcn.com/) - Beautiful UI components
- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
- [Recharts](https://recharts.org/) - Composable charting library
- [Alpha Vantage](https://www.alphavantage.co/) - Financial data API
- [Finnhub](https://finnhub.io/) - Stock market API
---
## 🗺️ Roadmap
### Phase 1 - MVP ✅
- [x] Basic widget system
- [x] API integration
- [x] Drag and drop
- [x] Data persistence
### Phase 2 - Enhancement 🚧
- [ ] WebSocket for real-time data
- [ ] More chart types
- [ ] Advanced filters
- [ ] Portfolio tracking
### Phase 3 - Advanced Features 📋
- [ ] User authentication
- [ ] Cloud sync
- [ ] Collaborative dashboards
- [ ] AI-powered insights
- [ ] Mobile app (React Native)
- [ ] Alerts and notifications
---
## 📞 Contact
**Project Maintainer**: Aryan Bajpai
- Email: aryanbajpai2411@gmail.com
- GitHub: [@coderntome](https://github.com/codernotme)
- LinkedIn: [Your Profile](https://linkedin.com/in/codernotme)
**Project Link**: [https://github.com/codernotme/finboard](https://github.com/codernotme/finboard)
---
### ⭐ Star this repo if you find it helpful!
**Made with ❤️ for the finance community**
[Report Bug](https://github.com/codernotme/finboard/issues) · [Request Feature](https://github.com/codernotme/finboard/issues) · [Documentation](./docs)
---
## 📈 Project Stats
**Last Updated**: January 2026