AI-powered financial assistant for Nigerian tax calculations and bank statement analysis
TaxBracket AI is an intelligent financial assistant designed specifically for Nigerian taxpayers, accountants, and financial advisors. Upload your bank statements, get instant tax calculations based on the Nigeria Tax Act 2025, and receive AI-powered insights about your financial data.
- Nigerian Tax Expertise: Built with deep knowledge of Nigerian tax laws, brackets, and regulations
- Bank Statement Analysis: Automatically parse and analyze PDF, CSV, and Excel bank statements
- AI-Powered Insights: Get intelligent recommendations and calculations powered by GPT-4
- Privacy First: Your financial data stays secure with bank-level encryption
| Feature | Description |
|---|---|
| Bank Statement Analysis | Upload PDF, CSV, or XLSX bank statements for automatic parsing |
| Tax Calculations | Accurate calculations based on Nigeria Tax Act 2025 (effective 2026) |
| Financial Insights | Visual charts and data visualizations of your finances |
| Bank Charge Detection | Automatic identification of fees, charges, and deductions |
| Transaction Categorization | Smart categorization of income, expenses, and deductions |
| Rent Relief Calculation | Automatic rent relief deductions based on Nigerian tax law |
| Real-time Streaming | Responses stream in real-time with incremental block rendering |
| Credit System | Flexible credit-based usage with weekly resets or purchased credits |
| Category | Technologies |
|---|---|
| Framework | TanStack Start (React, SSR, File-based routing) |
| Database | PostgreSQL with Drizzle ORM |
| AI | OpenAI GPT-4o via Vercel AI SDK |
| Styling | Tailwind CSS |
| Storage | Cloudflare R2 (S3-compatible) |
| Queue | pg-boss (PostgreSQL-based job queue) |
| Authentication | Custom session-based auth with Google OAuth |
| Charts | Recharts |
| Payments | Polar (optional, for credit purchases) |
- Node.js 18+
- PostgreSQL 14+
- npm or yarn
- OpenAI API key (for AI features)
- Clone the repository
git clone https://github.com/taxbracket/taxbracket.git
cd taxbracket- Install dependencies
npm install- Set up environment variables
cp .env.example .envEdit .env with your configuration:
# Required
DATABASE_URL=postgresql://postgres:password@localhost:5432/taxbracket
SESSION_SECRET=your-secure-random-secret-min-32-chars
OPENAI_API_KEY=sk-...
# Required for file uploads
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_ACCESS_KEY=your-access-key
CLOUDFLARE_SECRET_ACCESS_KEY=your-secret-access-key
S3_BUCKET_NAME=taxbracket-uploads
# Required for OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback- Run database migrations
npm run db:migrate- Start the development server
npm run dev- Start the worker (for file processing)
In a separate terminal:
npx tsx scripts/worker.tsVisit http://localhost:3000 to see the application.
taxbracket/
├── src/
│ ├── components/ # React components
│ │ ├── chat/ # Chat interface components
│ │ ├── charts/ # Chart and visualization components
│ │ ├── credits/ # Credit system UI
│ │ ├── layout/ # Layout components (sidebar, header)
│ │ └── ui/ # Base UI components
│ ├── db/ # Database schema and migrations
│ ├── hooks/ # React hooks
│ ├── lib/ # Utility functions
│ ├── routes/ # File-based routes
│ │ └── api/ # API routes
│ ├── server/ # Server-side code
│ │ ├── data/ # System prompts and static data
│ │ ├── functions/ # Server functions
│ │ ├── jobs/ # Background jobs
│ │ ├── lib/ # Server utilities
│ │ └── middleware/ # Request middleware
│ └── workers/ # Background workers
├── drizzle/ # Database migrations
├── public/ # Static assets
└── scripts/ # CLI scripts
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection string |
SESSION_SECRET |
Yes | Session encryption key (min 32 chars) |
OPENAI_API_KEY |
Yes | OpenAI API key for AI features |
CLOUDFLARE_* |
Yes | Cloudflare R2 credentials for file storage |
GOOGLE_CLIENT_ID |
Yes | Google OAuth client ID |
GOOGLE_CLIENT_SECRET |
Yes | Google OAuth client secret |
SITE_URL |
No | Production URL (default: https://taxbracketai.com) |
CREDITS_WEEKLY_LIMIT |
No | Weekly credit limit (default: 1000) |
CREDITS_PER_TOKEN |
No | Credit-to-token ratio (default: 0.1) |
BETA_MODE |
No | Enable beta features (default: true) |
CREDIT_PURCHASE_ENABLED |
No | Enable credit purchases (default: false) |
POLAR_API_KEY |
No | Polar API key for payments |
# Development
npm run dev # Start dev server
npm run build # Build for production
npm run start # Start production server
# Database
npm run db:generate # Generate migrations
npm run db:migrate # Run migrations
npm run db:studio # Open Drizzle Studio
# Testing
npm run test # Run tests
npm run typecheck # TypeScript type checking
npm run lint # ESLintThe worker handles file processing and scheduled jobs:
# Development
npx tsx scripts/worker.ts
# Production (Railway)
# Use separate service with railway.worker.json config- Connect your GitHub repository to Vercel
- Set environment variables in Vercel dashboard
- Deploy
- Create a new project from GitHub
- Add PostgreSQL service
- Set environment variables
- Create separate service for worker using
railway.worker.json
We welcome contributions! Please follow these guidelines:
- Fork the repository and create a feature branch
- Make your changes following our code style
- Add tests for new features
- Update documentation as needed
- Submit a pull request with a clear description
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/taxbracket.git
cd taxbracket
# 2. Create a branch
git checkout -b feature/amazing-feature
# 3. Make changes and commit
git commit -m 'Add amazing feature'
# 4. Push and create PR
git push origin feature/amazing-feature- Follow TypeScript best practices
- Use Prettier for formatting (
npm run format) - Write meaningful commit messages
- Add JSDoc comments for complex functions
- Follow the existing project structure
- Use GitHub Issues for bug reports and feature requests
- Include reproduction steps for bugs
- Search existing issues before creating new ones
- RAG Implementation - Reduce token usage with vector-based retrieval
- Template Responses - Fast responses for common queries
- Response Caching - Cache frequent calculations
- Mobile App - React Native mobile application
- Multi-language - Support for Hausa, Yoruba, and Igbo
- Tax Filing - Direct FIRS integration for tax filing
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with TanStack Start
- AI powered by OpenAI
- UI components inspired by shadcn/ui
- Charts by Recharts
- Icons by Lucide
- GitHub Issues - Bug reports and feature requests
- Discussions - Questions and community