A comprehensive invoice management system built with Go and Next.js, featuring AI-powered search and Model Context Protocol (MCP) integration.
- 📄 Invoice Management: Create, read, update, and delete invoices with detailed line items
- 🏢 Company & Receiver Management: Organize vendors and invoice recipients
- 🏷️ Categories & Tags: Flexible categorization and tagging system
- 📊 Analytics & Reporting: Built-in analytics and statistics dashboard
- 📤 File Upload: S3-compatible storage for invoice attachments
- 🔍 AI-Powered Search: Intelligent search capabilities using AI SDK
- 🤖 MCP Server: Model Context Protocol integration for AI assistants
- 💱 Currency Support: Multi-currency with exchange rate conversion
- 🔐 OAuth Authentication: Secure authentication with JWT tokens
- 📱 Responsive UI: Modern Next.js frontend with mobile support
- Go 1.25+: Main backend language
- Fiber v2: Fast HTTP framework
- GORM: ORM for database operations
- Turso/SQLite: Database (supports both local SQLite and Turso)
- AWS SDK v2: S3-compatible storage integration
- MCP Go: Model Context Protocol server implementation
- OpenAPI 3.0: API specification and code generation
- Next.js 16: React framework
- TypeScript: Type-safe development
- TanStack Query: Data fetching and caching
- TanStack Table: Advanced table components
- Shadcn UI: Component library
- Tailwind CSS: Utility-first styling
- React Hook Form: Form management with Zod validation
- Recharts: Data visualization
- AI SDK: AI-powered features
- Go 1.25 or higher
- Node.js 20 or higher
- Docker & Docker Compose (optional)
- Bun or npm package manager
Create a .env file in the root directory with the following variables:
# Server
PORT=8080
# Database (Turso) - Leave empty to use local SQLite
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
# S3-compatible storage
S3_ENDPOINT=your-s3-endpoint
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1
S3_USE_PATH_STYLE=false
# Authentication
MCPROUTER_SERVER_URL=your-mcprouter-url
MCPROUTER_SERVER_API_KEY=your-api-key
OAUTH_SERVER_URL=your-oauth-server
OAUTH_ISSUER=your-oauth-issuer
OAUTH_AUDIENCE=your-oauth-audience
# File Server (for unlinking files)
FILE_SERVER_URL=your-file-server-url# Start the application
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the application
docker-compose downBackend:
# Install dependencies
make deps
# Generate OpenAPI code
make generate
# Build the binary
make build
# Run the server
make run
# Or run with hot reload (requires air)
airFrontend:
cd frontend
# Install dependencies
bun install
# Run development server
bun dev
# Build for production
bun buildBackend:
make deps # Download and tidy dependencies
make build # Build the binary
make run # Run the server
make test # Run tests
make test-e2e # Run E2E tests
make test-coverage # Run tests with coverage
make fmt # Format code
make lint # Lint code
make generate # Generate OpenAPI code
make clean # Clean build artifacts
make install-local # Install binary to /usr/local/binFrontend:
bun dev # Start development server
bun build # Build for production
bun start # Start production server
bun lint # Run ESLint.
├── cmd/
│ └── server/ # Main application entry point
├── internal/
│ ├── api/ # API server and handlers
│ │ ├── handlers/ # HTTP request handlers
│ │ ├── middleware/ # Middleware functions
│ │ └── generated/ # OpenAPI generated code
│ ├── assets/ # Static assets and OpenAPI spec
│ ├── mcp/ # Model Context Protocol server
│ ├── models/ # Database models
│ ├── services/ # Business logic services
│ ├── tools/ # MCP tools implementation
│ └── utils/ # Utility functions
├── frontend/ # Next.js frontend application
│ ├── app/ # Next.js app directory
│ │ ├── (auth)/ # Authentication pages
│ │ ├── (dashboard)/ # Dashboard pages
│ │ └── api/ # API routes
│ ├── components/ # React components
│ ├── hooks/ # Custom React hooks
│ └── lib/ # Utility libraries and API clients
├── e2e/ # End-to-end tests
├── k8s/ # Kubernetes deployment configs
└── oapi-codegen/ # OpenAPI code generation configs
The API follows OpenAPI 3.0 specification. Key endpoints include:
/api/health- Health check/api/categories- Category management/api/companies- Company/vendor management/api/receivers- Invoice receiver management/api/tags- Tag management/api/invoices- Invoice CRUD operations/api/invoices/{id}/items- Invoice line items/api/upload- File upload operations/api/analytics/*- Analytics and statistics
Full API documentation is available in internal/assets/openapi.yaml.
This project includes a Model Context Protocol (MCP) server that allows AI assistants to interact with the invoice management system. The MCP server provides tools for:
- Creating, reading, updating, and deleting invoices
- Managing categories, companies, receivers, and tags
- Uploading and managing files
- Generating analytics and statistics
The MCP server is automatically started alongside the main API server.
Kubernetes deployment configurations are available in the k8s/ directory:
cd k8s
# Apply all configurations
kubectl apply -k .
# Or apply individually
kubectl apply -f namespace.yaml
kubectl apply -f secrets.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml
kubectl apply -f cluster-issuer.yamlSee k8s/README.md for detailed deployment instructions.
Unit Tests:
make testE2E API Tests:
make test-e2eCoverage Report:
make test-coverage- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is maintained by RxTech Lab.
For issues and questions, please open an issue on GitHub.