✨ Finarva AI Backend is a production-ready, enterprise-grade platform built with NestJS, designed to empower microentrepreneurs with intelligent financial and operational tools. Featuring advanced AI capabilities, comprehensive business analytics, and seamless integration with modern financial services.
- Merchant Assistant: LLM-powered guidance with RAG architecture and Pinecone vector database
- Financial Advisory: Personalized recommendations using OpenAI GPT-4 and Google Gemini
- Smart Analytics: Machine learning-driven insights for business optimization
- Multi-language Support: Localized AI responses in native languages
- Expense Tracking: Real-time expense categorization and management
- Cash Flow Analysis: Predictive analytics for financial health monitoring
- Investment Advisory: AI-driven investment recommendations
- Insurance Management: Tailored insurance suggestions and tracking
- Micro-loans: Seamless integration with lending platforms
- Supply Chain Management: Inventory tracking and optimization
- Client Management: Comprehensive CRM with detailed profiles
- Reporting & Analytics: Advanced business intelligence dashboards
- Learning Recommendations: Personalized educational content delivery
- Interactive Quizzes: Multilingual engagement tools
- JWT Authentication: Secure token-based authentication with refresh tokens
- Rate Limiting: Advanced request throttling and DDoS protection
- Data Encryption: End-to-end encryption for sensitive data
- Audit Logging: Comprehensive security event tracking
- GDPR Compliance: Privacy-first data handling
graph TB
Client[Client Applications] --> LB[Load Balancer]
LB --> API[Finarva API]
API --> Cache[Redis Cache]
API --> DB[(PostgreSQL)]
API --> Vector[(Pinecone Vector DB)]
API --> Queue[BullMQ]
API --> OpenAI[OpenAI GPT-4]
API --> Gemini[Google Gemini]
API --> Stripe[Stripe Payments]
Queue --> Workers[Background Workers]
- Framework: NestJS with TypeScript
- Database: PostgreSQL with Prisma ORM
- Cache: Redis for session management and caching
- Queue: BullMQ for background job processing
- AI Services: OpenAI GPT-4, Google Gemini Pro
- Vector Database: Pinecone for AI knowledge base
- Payment Processing: Stripe integration
- Documentation: Swagger/OpenAPI 3.0
- Testing: Jest with comprehensive E2E coverage
- Deployment: Docker with multi-stage builds
- Node.js 18+ with npm 8+
- PostgreSQL 14+
- Redis 6+
- Docker (optional)
-
Clone the repository
git clone https://github.com/techySPHINX/Finarva.git cd Finarva -
Install dependencies
npm install
-
Environment setup
cp .env.example .env # Edit .env with your configuration -
Database setup
npm run prisma:generate npm run prisma:migrate npm run prisma:seed
-
Start development server
npm run start:dev
-
Access the application
- API: http://localhost:3000
- Documentation: http://localhost:3000/api/docs
- Health Check: http://localhost:3000/health
-
Development with Docker Compose
docker-compose up -d
-
Production build
docker build -t finarva-api . docker run -p 3000:3000 finarva-api
- Swagger UI:
/api/docs- Interactive API explorer - ReDoc:
/api/redoc- Alternative documentation view - OpenAPI Spec:
/api/docs-json- Raw OpenAPI specification
| Category | Endpoint | Description |
|---|---|---|
| Authentication | POST /api/v1/auth/login |
User authentication |
| Users | GET /api/v1/users/profile |
User profile management |
| Financial | GET /api/v1/cash-flow/analysis |
Cash flow analytics |
| AI | POST /api/v1/ai/advice |
AI-powered financial advice |
| Health | GET /health |
Application health status |
All authenticated endpoints require a Bearer token:
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://api.finarva.com/api/v1/users/profile# Unit tests
npm run test
# E2E tests
npm run test:e2e
# Test coverage
npm run test:cov
# All tests
npm run test:all
# CI testing
npm run test:ci- Unit Tests:
src/**/*.spec.ts - E2E Tests:
e2e-tests/**/*.e2e-spec.ts - Test Utilities:
e2e-tests/utils/ - Test Data:
e2e-tests/fixtures/
- Statements: > 80%
- Branches: > 75%
- Functions: > 80%
- Lines: > 80%
src/
├── auth/ # Authentication module
├── users/ # User management
├── financial/ # Financial services
├── ai/ # AI-powered features
├── common/ # Shared utilities
├── config/ # Configuration
├── health/ # Health checks
└── main.ts # Application entry point
e2e-tests/ # End-to-end tests
prisma/ # Database schema
docs/ # Additional documentation
| Command | Description |
|---|---|
npm run start:dev |
Start development server |
npm run build |
Build for production |
npm run lint |
Run ESLint |
npm run format |
Format code with Prettier |
npm run prisma:studio |
Open Prisma Studio |
npm run docs:generate |
Generate code documentation |
- ESLint: Comprehensive linting rules
- Prettier: Consistent code formatting
- Husky: Git hooks for quality gates
- Commitizen: Conventional commit messages
- SonarQube: Code quality analysis
Deploy to Azure with complete infrastructure automation using Terraform:
# Navigate to infrastructure directory
cd infrastructure/azure
# Configure your deployment
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values
# Deploy infrastructure
terraform init
terraform apply
# Deploy application
cd ..
./scripts/deploy-to-azure.sh <VM_IP> azureuserFeatures:
- ✅ Complete infrastructure as code (Terraform)
- ✅ Auto-configured VM with Docker, Nginx, SSL
- ✅ Managed Redis Cache and optional PostgreSQL
- ✅ Application Insights monitoring
- ✅ Automated backups and security updates
- ✅ One-command deployment script
📖 See Infrastructure Guide for detailed Azure deployment instructions
# Build and run with Docker Compose
docker-compose up -d
# Or build manually
docker build -t finarva-api .
docker run -p 3000:3000 finarva-api# Build application
npm run build
# Run production server
npm run start:prodKey environment variables for deployment:
# Application
NODE_ENV=production
PORT=3000
API_PREFIX=api/v1
# Database
DATABASE_URL=postgresql://...
# AI Services
OPENAI_API_KEY=sk-...
GOOGLE_AI_API_KEY=...
PINECONE_API_KEY=...
# Security
JWT_SECRET=...
CORS_ORIGIN=https://yourdomain.com
# Azure (when using Azure deployment)
REDIS_HOST=your-redis.redis.cache.windows.net
REDIS_PASSWORD=...
APPINSIGHTS_INSTRUMENTATIONKEY=...See .env.example and .env.production.example for complete configuration.
- Environment variables configured
- Database migrations applied
- SSL certificates installed
- Monitoring configured (Application Insights or similar)
- Backup strategy implemented
- Load balancer configured (if needed)
- CDN setup for static assets (optional)
- Log aggregation configured
- Health check endpoints verified
- Security headers enabled (Helmet)
- Rate limiting configured
- Continuous Integration: Automated testing, linting, and security checks
- Continuous Deployment: Automated deployment to staging and production
- Quality Gates: Code coverage, security scans, performance tests
- Rollback Strategy: Automated rollback on deployment failures
Workflows:
.github/workflows/ci.yaml- Comprehensive CI pipeline.github/workflows/deploy.yaml- Production deployment.github/workflows/codeql.yml- Security analysis
- Health Checks:
/health,/health/live,/health/ready - Metrics: Custom business metrics and performance indicators
- Logging: Structured logging with correlation IDs
- Tracing: Distributed tracing for microservices
- Response Time: < 200ms for 95th percentile
- Throughput: 1000+ requests per second
- Uptime: 99.9% availability target
- Error Rate: < 0.1% error rate
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
- Follow TypeScript and NestJS best practices
- Write comprehensive tests
- Update documentation
- Use conventional commit messages
- Ensure all CI checks pass
This project is licensed under the MIT License.
- Documentation: docs.finarva.com
- API Reference: api.finarva.com/docs
- Support: support@finarva.com
- Security: security@finarva.com
- NestJS team for the amazing framework
- Prisma team for the excellent ORM
- OpenAI and Google for AI services
- The open-source community
Made with ❤️ by the Finarva Team
- Background Job Processing: Integrated BullMQ to manage long-running tasks asynchronously, ensuring the main application remains fast and responsive.
- Optimized Database Queries: Enhanced query performance through indexing strategies and optimized data access patterns, reducing response times.
- Database Scalability: Implemented a read-replica database strategy to distribute load and improve data availability for read-heavy operations.
- High Availability: Leveraged Node.js Clustering to run multiple application instances in parallel, improving CPU utilization and overall throughput.
| Layer | Technology |
|---|---|
| Backend | NestJS |
| Database | PostgreSQL + Prisma |
| AI Models | OpenAI GPT-4 / Gemini Pro |
| Vector DB | Pinecone |
| Documentation | Swagger + class-validator |
| Deployment | Ready for Docker / CI-CD Pipelines |
📦 src
├── ai/ # AI Integration layer (Gemini/OpenAI)
├── analytics/ # Business analytics and reporting
├── app.controller.ts # Main app controller
├── app.module.ts # Main app module
├── app.service.ts # Main app service
├── auth/ # Authentication and authorization
├── cash-flow/ # Cash flow analysis and forecasting
├── clients/ # Client module (profile, preferences)
├── common/ # Shared DTOs and utilities
├── expenses/ # Expense tracking and management
├── insurance/ # Insurance suggestion logic
├── inventory/ # Inventory and supply chain management
├── investment/ # Investments & recommendations
├── invoicing/ # Invoice creation, Stripe integration
├── learning/ # Content learning logic
├── loans/ # Micro-loan and credit facilitation
├── main.ts # App entry point
├── merchant-assistant/ # AI-powered merchant assistant
├── prisma/ # Prisma service integration
├── quiz/ # Quiz suggestion, history & records
├── reporting/ # Business analytics and reporting
├── tax/ # Tax calculation and reporting
├── types/ # Shared types
├── vector-store/ # Pinecone vector store integration
📦 prisma/ └── schema.prisma # Prisma schema definition
📦 test/ ├── app.e2e-spec.ts # End-to-end tests ├── jest-e2e.json # Jest config for e2e └── mocks/ # Mock services for testing
Other root files: ├── .env # Environment variables ├── Dockerfile # Docker setup ├── package.json # Project dependencies ├── README.md # Project documentation └── ... # Configs, scripts, etc.
- Node.js v18+
- PostgreSQL (Local or Docker)
- Prisma CLI
- OpenAI / Gemini API Key
- Pinecone API Key
git clone https://github.com/your-username/finarva-ai-backend
cd finarva-ai-backend
npm installCreate a .env file in the root with the following content:
DATABASE_URL="postgresql://user:password@localhost:5432/finarva"
OPENAI_API_KEY=sk-xxx
GEMINI_API_KEY=your-gemini-key
PINECONE_API_KEY=your-pinecone-keynpx prisma generate
npx prisma db pushnpm run start:devAccess the interactive Swagger documentation at:
http://localhost:3000/api
Explore all endpoints, test requests, and view schemas.
npm run lint # Run linter
npm run test # Run unit testsThis project is licensed under the MIT License.
We welcome contributions! Please follow the standard GitHub flow: fork, branch, commit, and pull request.
🚀 Empowering the next generation of microentrepreneurs through intelligence.