README.md

DutchTax Platform

A comprehensive Dutch tax automation platform with Revolut Business API integration for seamless transaction management and tax calculations.

🚀 Features

Core Platform

• Dashboard Overview - Financial insights and key metrics
• Transaction Management - Import and categorize transactions
• Account Management - Multi-account support with balance tracking
• Invoice Management - Create and manage invoices
• Tax Calculator - Dutch tax calculations with VAT support
• Settings Management - User preferences and integrations

Revolut Integration

• Secure OAuth Flow - Industry-standard authentication
• Per-User Certificates - Individual RSA key pairs for each user
• Automatic Token Refresh - Seamless API access management
• Account Syncing - Real-time account and transaction data
• Multi-Environment Support - Sandbox and production ready

AI Tax Agent (Gemini AI)

• Expert Tax Advice - Personalized Dutch tax guidance
• Transaction Categorization - AI-powered expense classification
• Tax Calculations - Intelligent tax liability computation
• Tax Optimization - Recommendations for tax efficiency
• Dutch Tax Compliance - Up-to-date 2025 tax rules
• Multi-Business Support - Eenmanszaak, BV, VOF, Maatschap

Tax Flow Processing

• Excel Integration - Upload and process Excel transaction files
• AI-Powered Categorization - Automatic Dutch tax categorization
• Batch Processing - Handle large transaction datasets efficiently
• Automated Tax Calculations - Generate tax liability from transactions
• Comprehensive Reports - AI-generated tax reports with recommendations
• Multi-Step Workflow - Upload → AI Processing → Calculate → Report
• Downloadable Reports - Export tax analysis in text format

🛠 Tech Stack

• Frontend: Next.js 13+ with App Router, React 18, TypeScript
• Styling: Tailwind CSS with custom design system
• Authentication: Supabase Auth
• Database: Supabase PostgreSQL
• Banking API: Revolut Business API
• AI Integration: Google Gemini AI
• Excel Processing: XLSX library
• Icons: Lucide React
• Deployment: Vercel (recommended)

📋 Prerequisites

• Node.js 18+
• npm or yarn
• Revolut Business account (for API access)
• Supabase account (for authentication and database)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/dutch-tax-platform.git
cd dutch-tax-platform

2. Install Dependencies

npm install

3. Environment Setup

Create a .env.local file in the root directory:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Revolut API Configuration (Optional - for production)
REVOLUT_SANDBOX_MODE=true

# Gemini AI Configuration
GEMINI_API_KEY=your_gemini_api_key

4. Run Development Server

npm run dev

Open http://localhost:3000 to view the application.

🔧 Revolut Integration Setup

For Development (Sandbox)

1. Sign up for Revolut Business Sandbox

   • Visit Revolut Developer Portal
   • Request sandbox access
   • Create a sandbox business account

2. Configure OAuth Redirect

   • Set redirect URI to: http://localhost:3000/api/revolut/callback
   • Note your Client ID for later use

For Production

1. Generate Production Certificates

   cd revolut-certs
   openssl genrsa -out privatecert.pem 2048
   openssl req -new -x509 -key privatecert.pem -out publiccert.cer -days 1825

2. Upload to Revolut Business

   • Go to Revolut Business web app
   • Navigate to Settings → APIs → Business API
   • Upload your public certificate
   • Set redirect URI to your production domain

📁 Project Structure

dutch-tax-platform/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API routes
│   │   │   └── revolut/       # Revolut integration APIs
│   │   ├── dashboard/         # Dashboard pages
│   │   └── globals.css        # Global styles
│   ├── components/            # React components
│   │   ├── auth/             # Authentication components
│   │   └── dashboard/        # Dashboard components
│   └── lib/                  # Utility libraries
│       └── revolut-integration.ts  # Revolut API client
├── revolut-certs/            # Certificate storage (gitignored)
├── public/                   # Static assets
└── package.json

🔐 Security Features

• OAuth 2.0 Compliance - Secure authentication flow
• RSA Key Pairs - Individual certificates per user
• Token Management - Automatic refresh and secure storage
• Environment Isolation - Separate sandbox/production configs
• Input Validation - Comprehensive data validation

🧪 Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

🚀 Deployment

Vercel (Recommended)

1. Connect Repository

   • Push code to GitHub
   • Connect repository to Vercel
   • Configure environment variables

2. Environment Variables

   NEXT_PUBLIC_SUPABASE_URL=your_production_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_production_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_production_service_role_key
   NEXT_PUBLIC_APP_URL=https://your-domain.vercel.app
   REVOLUT_SANDBOX_MODE=false

Manual Deployment

# Build for production
npm run build

# Start production server
npm start

📊 API Documentation

Revolut Integration Endpoints

• POST /api/revolut/connect - Initialize connection
• POST /api/revolut/authorize - Create OAuth URL
• GET /api/revolut/callback - Handle OAuth callback
• POST /api/revolut/sync - Sync accounts and transactions
• GET /api/revolut/sync - Get connection status

AI Tax Agent Endpoints

• POST /api/ai/tax-advice - Get personalized tax advice
• POST /api/ai/categorize - Categorize transactions
• POST /api/ai/calculate-tax - Calculate tax liability

Tax Flow Processing Endpoints

• POST /api/tax-flow/process-excel - Process Excel file with AI categorization
• POST /api/tax-flow/calculate-tax - Calculate tax from processed transactions
• POST /api/tax-flow/generate-report - Generate comprehensive tax report

Authentication Endpoints

• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/user - Get current user

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgments

• Revolut Business API for banking integration
• Google Gemini AI for intelligent tax assistance
• Supabase for authentication and database
• Next.js for the React framework
• Tailwind CSS for styling
• Lucide for icons

---

Built with ❤️ for Dutch entrepreneurs and businesses.