FinFlow is a financial management backend API built with Node.js and TypeScript.
It includes authentication, payment processing, budgeting features, background jobs, and containerized deployment using Docker Swarm.
- Transaction Management - Track income and expenses with categories
- Budget Planning - Set monthly budgets with category allocations
- Category Management - System and custom categories for organizing transactions
- Analytics & Reports - Spending insights, trends, and budget comparisons
- OTP-based Authentication - Passwordless login via email OTP
- Google OAuth 2.0 - Social login integration
- JWT Tokens - Secure access and refresh token system
- Session Management - Multi-device session tracking with logout-all capability
- Rate Limiting - Redis-backed rate limiting for API protection
- Razorpay Integration - Payment processing with webhook support
- Subscription Plans - Free and Pro tier subscription management
- Payment History - Complete payment and invoice tracking
- Background Jobs - BullMQ for email queues and scheduled tasks
- File Storage - AWS S3 for avatar uploads with pre-signed URLs
- Docker Swarm - Production deployment with health checks
- CI/CD - GitHub Actions for testing, building, and deployment
Client / Browser
│
▼
Internet (HTTPS)
│
▼
┌──────────────────────── AWS Cloud (eu-north-1) ───────────────────────┐
│ │
│ ┌────────────── Docker Swarm Cluster (3 Manager Nodes) ────────────┐ │
│ │ │ │
│ │ Node Public Port :80 / :443 │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Swarm Routing Mesh │ │
│ │ (any node can accept traffic) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Caddy Service (replicas:1) │ │
│ │ Reverse Proxy + Auto TLS │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Swarm Service VIP (app:3000) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ FinFlow App Service (replicas:N) │ │
│ │ │ │
│ │ Manager Node 1 (Leader) → Replica(s) │ │
│ │ Manager Node 2 → Replica(s) │ │
│ │ Manager Node 3 → Replica(s) │ │
│ │ │ │
│ │ Overlay Network: finflow_net │ │
│ │ Docker Secrets (encrypted) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────┘
│
┌────────────┼────────────┬──────────────┐
▼ ▼ ▼ ▼
Neon PostgreSQL Upstash Redis AWS S3 Razorpay
(Prisma ORM) (BullMQ) File Storage Payments
│
▼
SMTP/Gmail
(Email)
Requests terminate at the Caddy reverse proxy, which forwards traffic to the Docker Swarm service. Docker Swarm distributes traffic across application replicas using its internal routing mesh and VIP load balancing.
For detailed architecture documentation, see Architecture
| Category | Technology |
|---|---|
| Runtime | Node.js 22, TypeScript |
| Framework | Express 5 |
| Database | PostgreSQL (Neon), Prisma ORM |
| Cache/Queue | Redis (Upstash), BullMQ |
| Authentication | JWT, Passport.js, Google OAuth |
| Payments | Razorpay |
| Storage | AWS S3 |
| Nodemailer, Mailgen | |
| Validation | Zod |
| Documentation | Swagger/OpenAPI |
| Testing | Vitest, Supertest |
| Deployment | Docker, Docker Swarm, Caddy |
| CI/CD | GitHub Actions |
- Node.js 22+
- Docker & Docker Compose
- PostgreSQL (or use Docker)
- Redis (or use Docker)
-
Clone the repository
git clone https://github.com/anuragsahu-dev/finflow-api.git cd finflow-api -
Install dependencies
npm install
-
Set up environment variables
cp .env.example .env # Edit .env with your configuration -
Start local services (PostgreSQL & Redis)
docker compose -f compose.dev.yaml up -d
-
Run database migrations
npx prisma migrate dev npm run seed
-
Start the development server
npm run dev
-
Access the API
- API:
http://localhost:3000/api/v1 - Swagger Docs:
http://localhost:3000/api-docs - Health Check:
http://localhost:3000/health
- API:
| Variable | Description | Required |
|---|---|---|
PORT |
Server port | Yes |
NODE_ENV |
Environment (development/production) | Yes |
DATABASE_URL |
PostgreSQL connection string | Yes |
REDIS_URL |
Redis connection string (Upstash) | Production |
REDIS_HOST |
Redis host (local development) | Development |
REDIS_PORT |
Redis port (local development) | Development |
ACCESS_TOKEN_SECRET |
JWT access token secret | Yes |
REFRESH_TOKEN_SECRET |
JWT refresh token secret | Yes |
ACCESS_TOKEN_EXPIRY |
Access token expiry (e.g., 15m) | Yes |
REFRESH_TOKEN_EXPIRY |
Refresh token expiry (e.g., 7d) | Yes |
SALT_ROUNDS |
Bcrypt salt rounds | Yes |
CLIENT_URL |
Frontend application URL | Yes |
APP_URL |
Backend API URL | Yes |
SMTP_HOST |
SMTP server host | Yes |
SMTP_PORT |
SMTP server port | Yes |
SMTP_USER |
SMTP username | Yes |
SMTP_PASS |
SMTP password | Yes |
GOOGLE_CLIENT_ID |
Google OAuth client ID | Yes |
GOOGLE_CLIENT_SECRET |
Google OAuth client secret | Yes |
GOOGLE_CALLBACK_URL |
Google OAuth callback URL | Yes |
RAZORPAY_KEY_ID |
Razorpay key ID | Yes |
RAZORPAY_KEY_SECRET |
Razorpay key secret | Yes |
RAZORPAY_WEBHOOK_SECRET |
Razorpay webhook secret | Yes |
AWS_REGION |
AWS region | Yes |
AWS_ACCESS_KEY_ID |
AWS access key | Yes |
AWS_SECRET_ACCESS_KEY |
AWS secret key | Yes |
AWS_S3_BUCKET_NAME |
S3 bucket name | Yes |
Interactive API documentation is available at /api-docs when the server is running.
| Module | Endpoints | Description |
|---|---|---|
| Auth | /api/v1/auth/* |
Authentication, OTP, Google OAuth |
| Users | /api/v1/users/* |
User profile, avatar management |
| Categories | /api/v1/categories/* |
Category CRUD operations |
| Transactions | /api/v1/transactions/* |
Transaction management |
| Budgets | /api/v1/budgets/* |
Budget planning and tracking |
| Analytics | /api/v1/analytics/* |
Reports and insights |
| Payments | /api/v1/payments/* |
Razorpay payments |
| Subscriptions | /api/v1/subscriptions/* |
Subscription management |
| Admin | /api/v1/admin/* |
Admin operations |
| Health | /health/* |
Health checks |
# Development
npm run dev # Start development server with hot reload
# Build
npm run build # Compile TypeScript to JavaScript
# Testing
npm test # Run all tests
npm run test:unit # Run unit tests only
npm run test:integration # Run integration tests only
npm run test:coverage # Run tests with coverage report
# Linting
npm run lint # Run ESLint
# Database
npm run seed # Seed the database
npx prisma migrate dev # Run migrations (development)
npx prisma migrate deploy # Run migrations (production)
npx prisma studio # Open Prisma Studiosrc/
├── config/ # Configuration (database, redis, swagger, etc.)
├── generated/ # Prisma generated client
├── infrastructure/ # External services (S3, payments, etc.)
├── jobs/ # Background jobs (BullMQ queues & workers)
├── middlewares/ # Express middlewares
├── modules/ # Feature modules
│ ├── admin/ # Admin operations
│ ├── analytics/ # Analytics & reports
│ ├── auth/ # Authentication
│ ├── budget/ # Budget management
│ ├── category/ # Categories
│ ├── health/ # Health checks
│ ├── otp/ # OTP service
│ ├── payment/ # Payment processing
│ ├── session/ # Session management
│ ├── subscription/ # Subscriptions
│ ├── transaction/ # Transactions
│ └── user/ # User management
├── types/ # TypeScript type definitions
├── utils/ # Utility functions
├── app.ts # Express app setup
└── index.ts # Server entry point
prisma/
├── schema.prisma # Database schema
├── migrations/ # Database migrations
└── seed.ts # Database seeding
test/
├── unit/ # Unit tests
└── integration/ # Integration tests
.github/
└── workflows/ # GitHub Actions workflows
├── ci.yaml # Continuous Integration
├── build.yaml # Docker image build
├── deploy.yaml # Deployment to server
└── migrate.yaml # Database migrations
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test file
npm test -- path/to/test.tsThis project is licensed under the ISC License.
Anurag Sahu
- GitHub: @anuragsahu-dev
| Document | Description |
|---|---|
| Setup Guide | Complete development setup with Docker and local options |
| Payment System | Razorpay integration, payment flow, and webhook handling |
| Architecture | System design, tech choices, and module structure |