Vestara API

Digital Investment & Funding Platform

A secure, modular, and scalable backend API powering Vestara’s wallet system, investment marketplace, transaction engine, and administrative ecosystem.

Overview

Vestara API is designed as an event-driven fintech backend with strict financial consistency and modular domain isolation.

It provides:

Base URL



Production: [https://vestara-api.vercel.app/](https://vestara-api.vercel.app/)

Architecture Overview

Vestara follows a modular layered architecture built on Fastify + TypeScript with DI support.



Controller → Service → Repository → Database / External Services

System Design

flowchart TD
A[Client Apps] --> B[Fastify API Gateway]

B --> C[Auth Module]
B --> D[Wallet Module]
B --> E[Investment Module]
B --> F[Payment Module]
B --> G[Admin Module]

C --> H[(PostgreSQL)]
D --> H
E --> H
F --> H
G --> H

D --> I[Redis Queue - BullMQ]
E --> I
F --> I

I --> J[Workers Layer]
J --> K[ROI Engine]
J --> L[Payment Reconciliation]
J --> M[Notification System]
J --> N[Investment Lifecycle Processor]

Core Modules

1. Authentication Module

Handles secure onboarding and identity verification.

2. Wallet Module

Manages all financial balances and ledger updates.

3. Investment Module

Handles investment lifecycle and ROI logic.

States:


OPEN → FUNDING → ACTIVE → MATURED → COMPLETED

4. Payment Module

Manages external payment integrations.

5. Admin Module

Administrative control layer.

Data Layer

Core Entities

User


interface User {
  id: string;
  mobileNumber: string;
  passwordHash: string;
  isVerified: boolean;
  createdAt: Date;
}

Wallet


interface Wallet {
  userId: string;
  availableBalance: number;
  investedBalance: number;
  pendingBalance: number;
  totalEarnings: number;
}

Investment Product


interface InvestmentProduct {
  id: string;
  name: string;
  fundingGoal: number;
  minInvestment: number;
  maxInvestment: number;
  expectedReturn: number;
  duration: number;
  status: "OPEN" | "FUNDING" | "ACTIVE" | "MATURED";
}

Investment


interface Investment {
  id: string;
  userId: string;
  productId: string;
  amount: number;
  status: "ACTIVE" | "COMPLETED";
  startDate: Date;
  maturityDate: Date;
}

Transaction (Ledger Core)


interface Transaction {
  id: string;
  userId: string;
  type: "DEPOSIT" | "WITHDRAW" | "INVEST" | "RETURN";
  amount: number;
  method: string;
  status: "PENDING" | "COMPLETED" | "FAILED";
  createdAt: Date;
}

Authentication Flow

sequenceDiagram
participant User
participant API
participant OTP
participant DB
participant JWT

User->>API: Register / Login
API->>OTP: Generate OTP
OTP-->>User: SMS OTP
User->>API: Submit OTP
API->>DB: Validate OTP + User
API->>JWT: Issue Token
JWT-->>User: Access Token

Wallet Flow

flowchart TD
A[User Action] --> B[API Request]
B --> C[Transaction Created]
C --> D[Queue Job]
D --> E[Worker Processing]
E --> F[Ledger Update]
F --> G[Wallet Balance Sync]

Investment Flow

flowchart TD
A[User Invests] --> B[Validate Balance]
B --> C[Lock Funds]
C --> D[Create Investment Record]
D --> E[Funding Pool]

E --> F{Goal Reached?}
F -->|No| E
F -->|Yes| G[Activate Investment]

G --> H[ROI Worker]
H --> I[Credit Returns]
I --> J[Mark Completed]

Background Jobs

Powered by BullMQ + Redis

Workers

Security

Tech Stack

Background Processing

Rate Limiting

Error Format


{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

Design Principles

Folder Architecture


.
├── .env
├── .env.local
├── .github
│   └── workflows
│       └── sync-subscribers.yml
├── docs
│   ├── Architecture.md
│   └── Workflow.md
├── src
│   ├── config
│   │   ├── env.ts
│   │   └── logger.ts
│   │
│   ├── modules
│   │   ├── subscribers
│   │   │   ├── subscribers.route.ts
│   │   │   ├── subscribers.service.ts
│   │   │   └── subscribers.types.ts
│   │   │
│   │   ├── upload
│   │   │   ├── upload.route.ts
│   │   │   ├── upload.service.ts
│   │   │   └── upload.types.ts
│   │   │
│   │   └── sync
│   │       ├── sync.route.ts
│   │       ├── sync.service.ts
│   │       └── sync.types.ts
│   │
│   ├── scripts
│   │   └── sync-subscribers.ts
│   │
│   ├── shared
│   │   ├── constants
│   │   ├── errors
│   │   ├── types
│   │   └── utils
│   │
│   ├── bootstrap
│   │   ├── register-plugins.ts
│   │   └── register-routes.ts
│   │
│   ├── plugins
│   │   └── swagger.plugin.ts
│   │
│   ├── app.ts
│   └── server.ts
│
├── README.md
├── package.json
├── package-lock.json
└── tsconfig.json


src
├── bootstrap
├── config
├── modules
│   ├── auth
│   ├── users
│   ├── wallet
│   ├── investments
│   ├── transactions
│   ├── payments
│   ├── subscribers
│   ├── uploads
│   └── admin
├── jobs
├── plugins
├── shared
│   ├── constants
│   ├── dto
│   ├── errors
│   ├── types
│   └── utils
├── app.ts
└── server.ts


src/
├── modules/
│   ├── auth/
│   ├── wallet/
│   ├── investment/
│   ├── payment/
│   ├── admin/
│
├── jobs/
├── plugins/
├── shared/
├── config/
├── database/
└── bootstrap/

Conclusion

Vestara API is a modular fintech backend designed for high reliability, financial accuracy, and scalable investment processing. It is built to support real-time transactions, automated ROI workflows, and secure multi-user financial operations.