FinAI is a comprehensive, multi-tenant platform designed to empower micro-entrepreneurs with AI-driven financial insights, automated order management, and seamless payment integrations.
- AI Financial Coach: Get real-time insights into your business health using our LangChain-powered assistant with Model Context Protocol (MCP) integration.
- Automated Payments: Seamless M-Pesa STK Push integration for instant, verifiable sales and automated reconciliation.
- WhatsApp Order Capture: Automatically capture orders from WhatsApp messages using Twilio and AI-driven keyword extraction.
- Inventory & Sales Tracking: Real-time stock management with background inventory updates and comprehensive sales logging.
- AI Marketing Tools: Generate stunning product images and social media content directly within the app using Pollinations AI.
- Business Insights: Detailed analytics on sales trends, expenses, and overall financial health.
- Multi-Tenancy: Secure, isolated data management for multiple businesses on a single platform.
| Component | Technologies |
|---|---|
| Backend | Node.js, Express, TypeScript, Prisma ORM, PostgreSQL |
| Mobile | React Native, Expo, NativeWind (Tailwind), TanStack Query |
| Frontend | React, Vite, Tailwind CSS |
| Infrastructure | Redis, BullMQ (Background Workers), Docker |
| AI/LLM | LangChain, Model Context Protocol (MCP), Pollinations AI |
├── backend/ # Express API, Database logic, and AI Agent
│ ├── chatbot/ # AI Agent logic, MCP server, and prompts
│ ├── prisma/ # Database schema and migrations
│ ├── services/ # Business logic layer
│ ├── workflows/ # BullMQ background workers
│ └── main.ts # Backend entry point
├── mobile/ # React Native (Expo) Mobile Application
│ ├── app/ # Expo Router screens (Dashboard, Sales, AI Coach)
│ ├── components/ # Reusable UI components
│ └── contexts/ # Global state (Auth, Business context)
├── frontend/ # React (Vite) Web Management Dashboard
└── ...
- Node.js (v18+)
- Bun (Recommended for backend performance)
- PostgreSQL (Running instance)
- Redis (Required for background workers)
Navigate to both backend/ and mobile/ directories and set up your environment files:
# In backend/
cp .env.example .env
# Update DATABASE_URL, JWT_SECRET, and REDIS_URL
# In mobile/
cp .env.example .env
# Set EXPO_PUBLIC_API_URL to your machine's LAN IPIn the backend/ directory:
npm install
npx prisma migrate dev --name init
npx prisma db seed# Using Docker (Recommended)
docker run --name final-redis -p 6379:6379 -d redis# In backend/
bun run start # or npm start# In mobile/
npx expo start# In frontend/
npm install
npm run devSet your live backend URL only in the Render dashboard and EAS secrets — do not commit production URLs or credentials to this repository.
Root directory: backend
Build command (use &&, not spaces — avoid bun install bunx prisma generate, which installs Prisma 7):
bun install && bunx prisma@6.16.3 generateStart command:
bunx prisma@6.16.3 migrate deploy && bun startAlternative using locked node_modules Prisma (see backend/package.json scripts):
# Build: bun install
# Start: bun run db:migrate:deploy && bun startOptional: apply render.yaml as a Render Blueprint for the same commands.
| Variable | Purpose |
|---|---|
DATABASE_URL |
Postgres connection for the running app |
DIRECT_URL |
Same external Postgres URL for prisma migrate deploy (required by schema) |
JWT_SECRET |
Auth token signing |
REDIS_URL |
BullMQ / Redis subscriber |
PORT |
Set by Render (usually 10000) |
Render Postgres: use the External connection string (hostname like dpg-....frankfurt-postgres.render.com) for both DATABASE_URL and DIRECT_URL. Do not use the internal dpg-...-a host outside Render’s private network.
Supabase: use the pooler URL for DATABASE_URL and db.<ref>.supabase.co:5432 for DIRECT_URL.
Set in EAS secrets or a local .env file (gitignored), not in tracked files:
EXPO_PUBLIC_API_URL=https://your-render-service.onrender.comSee mobile/.env.example. Rebuild the app after changing this value.
Replace YOUR_API_HOST with the host from your Render service URL:
export API_HOST=https://your-render-service.onrender.com
# Public uptime ping (no auth) — use for Render/cron keep-alive
curl -s "$API_HOST/api/public/health"
curl -s "$API_HOST/health"
curl -s -X POST "$API_HOST/api/auth/login" \
-H "Content-Type: application/json" -d '{}'
# Expect HTTP 400 with a validation message, not 500If Render logs Blocked 1 postinstall, run bun pm untrusted locally, review the package, and trust only if required for your deployment.
All backend API requests should be prefixed with /api. Ensure businessId is included in relevant requests for multi-tenancy.
| Module | Endpoints | Description |
|---|---|---|
| Business | /api/business |
Manage business registration and M-Pesa config. |
| Customers | /api/customers |
Manage customer records per business. |
| Products | /api/products |
Inventory management and AI image generation. |
| Orders | /api/orders |
Sales transactions and M-Pesa STK Push. |
| Expenses | /api/expenses |
Track operational costs and recurring bills. |
| Chatbot | /api/chatbot/chat |
AI-powered financial assistant interface. |
| Task | Command |
|---|---|
| Backend Test | npm test |
| Database Studio | npx prisma studio |
| Chatbot CLI | bun run chatbot |
| Seed Data | npx prisma db seed |
| Mobile Web | npx expo start --web |
- Asynchronous Processing: Inventory updates and sales logging are handled by background workers. Allow a few seconds for data to reflect after a successful payment.
- Error Handling: The API returns standard JSON errors:
{ "status": "error", "message": "..." }. - Branding: All components should align with the FinAI brand identity.