Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/najmulhossainnj/Hedge-fund-backend/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, spinning up the required infrastructure, running database migrations, and starting both the FastAPI server and the Celery worker — all on your local machine. By the end you will have a fully operational Research Layer instance and will have created your first strategy via the REST API.

​
Prerequisites

Before you begin, make sure the following are available on your machine:
  • Python 3.12+ — the project targets the CPython 3.12 runtime; earlier versions are not tested.
  • Docker — used to run Postgres, Redis, MinIO, and MLflow as local containers without a system-wide install of each service.
  • Git — to clone the repository.
All Python dependencies — including PyTorch, vectorbt, Backtrader, and the HuggingFace Transformers stack — are declared in requirements.txt and installed into a local virtualenv. No system-level installation of any ML framework is required.

​
Installation

1

Clone the repository and create a virtual environment

git clone https://github.com/najmulhossainnj/Hedge-fund-backend.git
cd Hedge-fund-backend

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
2

Install Python dependencies

The full dependency set — FastAPI, SQLAlchemy, Celery, MLflow, XGBoost, vectorbt, FinBERT, and more — is pinned in requirements.txt for reproducibility.
pip install -r requirements.txt
Installation may take a few minutes on first run due to the size of the PyTorch and vectorbt wheels. A warm pip cache on subsequent installs is significantly faster.
3

Start infrastructure services with Docker

The platform depends on four external services: PostgreSQL (primary store), Redis (cache, Celery broker and result backend), MinIO (S3-compatible artifact store), and MLflow (experiment tracking). Run each as a Docker container:
# PostgreSQL
docker run -d --name research-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=research_layer \
  -p 5432:5432 \
  postgres:16-alpine

# Redis
docker run -d --name research-redis \
  -p 6379:6379 \
  redis:7-alpine

# MinIO (S3-compatible object storage)
docker run -d --name research-minio \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  -p 9000:9000 -p 9001:9001 \
  minio/minio server /data --console-address ":9001"

# MLflow tracking server (backed by MinIO for artifacts)
docker run -d --name research-mlflow \
  -p 5000:5000 \
  ghcr.io/mlflow/mlflow:v2.16.2 \
  mlflow server --host 0.0.0.0 --port 5000
MinIO’s browser console is available at http://localhost:9001. Log in with minioadmin / minioadmin and create two buckets manually — research-artifacts and feature-store — before running the application for the first time.
4

Configure environment variables

Copy the example environment file and edit it to match your local setup:
cp .env.example .env   # if an example file exists, otherwise create .env
Open .env and set (at minimum) the following variables — the defaults match the Docker containers started in the previous step:
# Service identity
APP_NAME="Research Layer"
APP_ENV=local

# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/research_layer

# Cache + Celery broker
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/2

# Object storage (MinIO)
S3_ENDPOINT_URL=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_ARTIFACTS=research-artifacts
S3_BUCKET_FEATURES=feature-store

# MLflow
MLFLOW_TRACKING_URI=http://localhost:5000
MLFLOW_EXPERIMENT_NAME=research-layer
MLFLOW_ARTIFACT_ROOT=s3://research-artifacts/mlflow

# External Market Data Layer
MARKET_DATA_URL=http://localhost:8001

# Messaging
KAFKA_BOOTSTRAP_SERVERS=localhost:9092
EVENT_BACKEND=noop   # use "noop" locally if Kafka is not running

# Security
SECRET_KEY=change-me-in-production
Never commit a .env file containing real credentials to version control. The SECRET_KEY default is intentionally insecure — replace it before deploying to any shared environment.
5

Apply database migrations

Alembic manages all schema changes. Generate the initial migration from the current ORM models and then apply it:
alembic revision --autogenerate -m "init schema"
alembic upgrade head
On subsequent schema changes (e.g., after a git pull), only alembic upgrade head is needed.
6

Start the FastAPI server

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
The --reload flag enables hot-reload on code changes — ideal for local development. For production use the Docker image instead (see the Deployment guide).Once the server is up, the health endpoint confirms everything is wired correctly:
curl http://localhost:8000/health
# {"status":"ok","service":"Research Layer","env":"local"}
7

Start the Celery worker (separate terminal)

Long-running tasks — model training, hyperparameter tuning, backtest execution, and feature generation — are dispatched to Celery workers. Open a second terminal, activate the same virtualenv, and start a worker:
source .venv/bin/activate
celery -A app.workers.celery_app worker --loglevel=info
The worker picks up tasks from Redis and runs the engine pipelines concurrently. The Dockerfile.worker image (with --concurrency=2) can be used for containerised deployments.

​
Your First Strategy

With the server running, create a strategy definition using a simple curl request. The strategy object acts as the root entity that ties together features, models, backtests, and validation runs: 
curl -X POST http://localhost:8000/api/v1/strategies \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Momentum RSI",
    "description": "RSI-based momentum strategy",
    "universe": ["AAPL", "MSFT"],
    "timeframe": "1d"
  }'
A successful response returns the newly created strategy record with its UUID, timestamps, and version: 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Momentum RSI",
  "description": "RSI-based momentum strategy",
  "universe": ["AAPL", "MSFT"],
  "timeframe": "1d",
  "version": 1,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}
Use the returned id as the strategy_id when creating features, backtest configs, or kicking off a model training run against this strategy’s universe.
Open http://localhost:8000/docs in your browser for the full interactive Swagger UI. Every endpoint is documented with request/response schemas, and you can send requests directly from the browser without writing curl commands.

​
Next Steps

Strategies

Learn how strategies tie together features, models, and backtest configurations into a coherent research pipeline.

Deployment

Deploy the API server and Celery worker as Docker containers, configure production environment variables, and connect to managed Postgres and Redis.

Plugin Architecture

Add custom feature plugins, ML model backends, signal generators, and backtest engines by implementing a base interface and registering a module.

API Reference: Strategies

Full reference for all strategy endpoints — create, read, update, delete, and promote to the Portfolio Layer.

Build docs developers (and LLMs) love

Get started for freeTalk to us