-[](https://github.com/Adeyemi-cmd/StepFi-API/actions/workflows/ci.yml) [](https://coveralls.io/github/supabase/cli?branch=develop) [](https://bitbucket.org/supabase-cli/setup-cli/pipelines) [
-](https://gitlab.com/sweatybridge/setup-cli/-/pipelines)
+# StepFi-API
-[Supabase](https://supabase.io) is an open source Firebase alternative. We're building the features of Firebase using enterprise-grade open source tools.
+**The off-chain brain of StepFi — auth, orchestration, indexing, and background jobs for reputation-based credit on Stellar.**
-This repository contains all the functionality for Supabase CLI.
+The NestJS backend that turns wallet signatures into sessions, builds and tracks Soroban transactions, and serves the data the StepFi clients render.
-- [x] Running Supabase locally
-- [x] Managing database migrations
-- [x] Creating and deploying Supabase Functions
-- [x] Generating types directly from your database schema
-- [x] Making authenticated HTTP requests to [Management API](https://supabase.com/docs/reference/api/introduction)
+[](https://github.com/StepFi-app/StepFi-API/actions/workflows/ci.yml)
+[](https://nestjs.com)
+[](https://fastify.dev)
+[](https://www.typescriptlang.org)
+[](https://stellar.org)
+[](./LICENSE)
-## Getting started
+[What it does](#-what-this-service-does) · [Where it fits](#-where-it-fits) · [Modules](#-modules) · [Quick start](#-quick-start) · [API](#-api-surface) · [Roadmap](#-roadmap)
-### Install the CLI
+
-Available via [NPM](https://www.npmjs.com) as dev dependency. To install:
+---
-```bash
-npm i supabase --save-dev
-```
-
-When installing with yarn 4, you need to disable experimental fetch with the following nodejs config.
-
-```
-NODE_OPTIONS=--no-experimental-fetch yarn add supabase
-```
-
-> **Note**
-For Bun versions below v1.0.17, you must add `supabase` as a [trusted dependency](https://bun.sh/guides/install/trusted) before running `bun add -D supabase`.
-
-
- macOS
-
- Available via [Homebrew](https://brew.sh). To install:
-
- ```sh
- brew install supabase/tap/supabase
- ```
-
- To install the beta release channel:
-
- ```sh
- brew install supabase/tap/supabase-beta
- brew link --overwrite supabase-beta
- ```
-
- To upgrade:
-
- ```sh
- brew upgrade supabase
- ```
-
-
-
- Windows
-
- Available via [Scoop](https://scoop.sh). To install:
-
- ```powershell
- scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
- scoop install supabase
- ```
-
- To upgrade:
-
- ```powershell
- scoop update supabase
- ```
-
+## 📖 What is StepFi?
-
- Linux
+StepFi extends small, uncollateralized loans to learners and interns based on an **on-chain reputation score** rather than assets. Sponsors fund a shared liquidity pool; borrowers draw loans sized and priced by their reputation, repay in installments, and grow their score. All money and trust live in [Soroban smart contracts](https://github.com/StepFi-app/StepFi-Contracts) on Stellar — and **StepFi-API is the service that sits between the clients and those contracts.**
- Available via [Homebrew](https://brew.sh) and Linux packages.
+## 🗺️ Where it fits
- #### via Homebrew
+
- To upgrade:
+The clients ([StepFi-App](https://github.com/StepFi-app/StepFi-App), [StepFi-Web](https://github.com/StepFi-app/StepFi-Web)) never talk to Stellar directly. They call this REST API over wallet-signature JWT; the API authenticates them, builds Soroban transactions, submits or hands back signed XDR, indexes on-chain state, and runs the scheduled jobs that keep everything in sync.
- ```sh
- brew upgrade supabase
- ```
+## ⚙️ What this service does
- #### via Linux packages
+- **Wallet-signature auth** — a challenge/nonce is signed by the user's Stellar wallet (Ed25519); a verified signature mints a JWT access + refresh pair. No passwords, no email.
+- **Loan & credit orchestration** — builds request/approve/fund/repay transactions against the Creditline contract and tracks their lifecycle.
+- **Reputation & credit scoring** — reads on-chain scores, caches them, and maps score → credit limit & APR.
+- **Liquidity, sponsors, vendors, vouching** — endpoints backing pool deposits, merchant onboarding, and mentor vouches.
+- **Indexing & jobs** — background workers (BullMQ + Redis) index chain events, refresh caches, clean up expired nonces, and reconcile transaction status.
+- **Observability** — structured Pino logs, Prometheus metrics, Sentry error tracking, and a health endpoint pinged on a schedule.
- Linux packages are provided in [Releases](https://github.com/supabase/cli/releases). To install, download the `.apk`/`.deb`/`.rpm`/`.pkg.tar.zst` file depending on your package manager and run the respective commands.
+## 🌐 Live deployment
- ```sh
- sudo apk add --allow-untrusted <...>.apk
- ```
-
- ```sh
- sudo dpkg -i <...>.deb
- ```
-
- ```sh
- sudo rpm -i <...>.rpm
- ```
-
- ```sh
- sudo pacman -U <...>.pkg.tar.zst
- ```
-
-
-
- Other Platforms
-
- You can also install the CLI via [go modules](https://go.dev/ref/mod#go-install) without the help of package managers.
-
- ```sh
- go install github.com/supabase/cli@latest
- ```
-
- Add a symlink to the binary in `$PATH` for easier access:
+| Resource | URL |
+|----------|-----|
+| **API base** | https://stepfi-api.onrender.com/api/v1 |
+| **Swagger docs** | https://stepfi-api.onrender.com/api/v1/docs |
+| **Health check** | https://stepfi-api.onrender.com/api/v1/health |
+
+> A scheduled GitHub Action ([`health-check.yml`](.github/workflows/health-check.yml)) pings the health endpoint every 6 hours to keep the Render free-tier instance warm and acts as a heartbeat monitor — a non-200 response opens/updates a GitHub issue with the `incident` label.
+
+
+
+## 🧩 Modules
+
+A NestJS application (`src/`) organized into feature modules under [`src/modules/`](src/modules), with cross-cutting `auth/`, `blockchain/`, `stellar/`, `indexer/`, `jobs/`, `database/`, `config/`, and `common/` layers.
+
+| Module | Responsibility |
+|--------|----------------|
+| **auth** | Wallet-signature challenge → JWT access/refresh; passport-jwt guards |
+| **users** / **learners** | Account and learner profile management |
+| **loans** | Loan lifecycle — request, approve, fund, repay against Creditline |
+| **credit-scoring** | Score → credit-limit & APR decisioning |
+| **reputation** | On-chain reputation reads with cache |
+| **liquidity** | Sponsor pool deposits, shares, withdrawals |
+| **sponsors** | Sponsor onboarding and positions |
+| **vendors** | Vendor registry — onboarding, catalog, payouts |
+| **vouching** | Mentor vouches that boost reputation |
+| **transactions** | Soroban transaction building & status tracking |
+| **blockchain** | Contract clients and network wiring |
+| **notifications** | User notifications |
+| **metrics** | Prometheus metrics endpoint |
+| **admin** | Privileged operations gated by `ADMIN_WALLETS` |
+| **health** | Liveness/readiness for the scheduled heartbeat |
+
+## 🧱 Tech stack
+
+| Layer | Choice |
+|-------|--------|
+| Framework | NestJS `11` on the **Fastify** adapter |
+| Language | TypeScript `5` |
+| Auth | `@nestjs/jwt` + `passport-jwt`; Stellar wallet-signature challenge |
+| On-chain | `stellar-sdk` (Horizon + Soroban RPC) |
+| Data | Supabase (`@supabase/supabase-js`) |
+| Queue / cache | BullMQ + `ioredis` (Redis), `@nestjs/cache-manager` |
+| Validation | `class-validator` / `class-transformer` + `zod` |
+| Hardening | `helmet`, `@nestjs/throttler` (rate limiting) |
+| Observability | `nestjs-pino`, `@willsoto/nestjs-prometheus`, `@sentry/nestjs` |
+| Docs | `@nestjs/swagger` (OpenAPI) |
+
+## 🚀 Quick start
+
+### Prerequisites
+
+| Tool | Notes |
+|------|-------|
+| Node.js | ≥ 20 (matches CI) |
+| npm | ≥ 10 |
+| Redis | for BullMQ jobs & caching |
+| Supabase project | database + storage |
+
+### Install & run
- ```sh
- ln -s "$(go env GOPATH)/bin/cli" /usr/bin/supabase
- ```
+```bash
+git clone https://github.com/StepFi-app/StepFi-API.git
+cd StepFi-API
+npm install
- This works on other non-standard Linux distros.
-
+cp .env.example .env # then fill in the values below
+npm run dev # watch mode on http://localhost:/api/v1
+```
-
- Community Maintained Packages
+### Configuration
- Available via [pkgx](https://pkgx.sh/). Package script [here](https://github.com/pkgxdev/pantry/blob/main/projects/supabase.com/cli/package.yml).
- To install in your working directory:
+Copy [`.env.example`](.env.example) and set at least:
- ```bash
- pkgx install supabase
- ```
+| Variable | Purpose |
+|----------|---------|
+| `PORT` · `API_PREFIX` · `ALLOWED_ORIGINS` | HTTP server & CORS |
+| `SUPABASE_URL` · `SUPABASE_ANON_KEY` · `SUPABASE_SERVICE_ROLE_KEY` | Supabase access |
+| `DATABASE_URL` | Postgres connection |
+| `REDIS_URL` | BullMQ queues & cache |
+| `JWT_SECRET` · `JWT_REFRESH_SECRET` | Token signing |
+| `AUTH_CHALLENGE_DOMAIN` | Domain bound into the signing challenge |
+| `STELLAR_NETWORK_PASSPHRASE` · `STELLAR_HORIZON_URL` · `STELLAR_SOROBAN_URL` | Stellar network |
+| `CREDITLINE_CONTRACT_ID` · `REPUTATION_CONTRACT_ID` · `LIQUIDITY_POOL_CONTRACT_ID` | Deployed contract IDs |
+| `SENTRY_DSN` · `SENTRY_TRACES_SAMPLE_RATE` | Error tracking (optional; no-op if unset) |
- Available via [Nixpkgs](https://nixos.org/). Package script [here](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/supabase-cli/default.nix).
-
+> Never commit real secrets. `.env` is git-ignored; only `.env.example` (placeholders) is tracked.
-### Run the CLI
+## 📜 Scripts
-```bash
-supabase bootstrap
-```
+| Command | What it does |
+|---------|--------------|
+| `npm run dev` | Start in watch mode |
+| `npm run build` | Compile with the Nest builder |
+| `npm run start:prod` | Run the compiled server (`dist/main`) |
+| `npm run lint:ci` | ESLint with `--max-warnings=0` (the CI gate) |
+| `npm test` | Jest unit tests |
+| `npm run test:cov` | Tests with coverage |
+| `npm run test:e2e` | End-to-end tests |
-Or using npx:
+## 🔌 API surface
-```bash
-npx supabase bootstrap
-```
+The full, always-current contract is the **OpenAPI/Swagger UI** at [`/api/v1/docs`](https://stepfi-api.onrender.com/api/v1/docs). Endpoints are grouped by the modules above (auth, loans, reputation, liquidity, sponsors, vendors, vouching, …). See also [StepFi-Docs](https://docs.page/StepFi-app/StepFi-Docs) for protocol-level guides.
-The bootstrap command will guide you through the process of setting up a Supabase project using one of the [starter](https://github.com/supabase-community/supabase-samples/blob/main/samples.json) templates.
+## 🛡️ Security & observability
-## 🌐 Live Deployment
+- **Auth:** wallet-signature challenge → JWT; refresh rotation; `passport-jwt` guards. Admin routes gated by `ADMIN_WALLETS`.
+- **Hardening:** `helmet` headers and `@nestjs/throttler` rate limiting on the HTTP layer.
+- **Logging & metrics:** structured Pino logs and Prometheus metrics (`/metrics` via the metrics module).
+- **Error tracking:** Sentry when `SENTRY_DSN` is set; silent no-op otherwise.
-| Resource | URL |
-|---|---|
-| **API Base** | https://stepfi-api.onrender.com/api/v1 |
-| **Swagger Docs** | https://stepfi-api.onrender.com/api/v1/docs |
-| **Health Check** | https://stepfi-api.onrender.com/api/v1/health |
+See [SECURITY.md](SECURITY.md) for the disclosure policy.
-> **Note**: A GitHub Action workflow pings the Health Check URL every 6 hours to keep the Render free tier instance warm and acts as a heartbeat monitor. If the ping fails (non-200 response), it automatically creates or updates a GitHub issue with the `incident` label to alert maintainers.
+## 🔄 CI/CD
-## 🛠️ Error tracking
+- [`ci.yml`](.github/workflows/ci.yml) — **required check on `main`**: `lint:ci` → `build` → `test:cov`.
+- [`health-check.yml`](.github/workflows/health-check.yml) — 6-hourly heartbeat against the live health endpoint, opening an `incident` issue on failure.
+- Deploys via [`render.yaml`](render.yaml) (Render).
-Error tracking is powered by Sentry. To enable error tracking in development or production:
+## 🛣️ Roadmap
-1. Create a Sentry project for Nest.js.
-2. Add the following environment variables to your `.env` file:
- ```env
- # Sentry DSN for error reporting
- SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
-
- # Optional: Sentry Traces Sample Rate (defaults to 0.1)
- SENTRY_TRACES_SAMPLE_RATE=0.1
- ```
-3. In production, unhandled exceptions will automatically be reported to Sentry. If `SENTRY_DSN` is not provided, the Sentry SDK will operate in no-op mode (silently) and the app will log unhandled exceptions only to stdout.
+Development is staged from core infrastructure to a full learner-financing ecosystem — see [ROADMAP.md](ROADMAP.md) for the phase-by-phase plan (auth & profiles, reputation, loans, liquidity, vouching, notifications, and hardening).
-## Docs
+## 🤝 Contributing
-Command & config reference can be found [here](https://supabase.com/docs/reference/cli/about).
+Keep `npm run lint:ci`, `npm run build`, and `npm test` green, and add tests for new behavior. See [CONTRIBUTING.md](CONTRIBUTING.md).
-## Breaking changes
+## 🌐 The StepFi protocol
-We follow semantic versioning for changes that directly impact CLI commands, flags, and configurations.
+| Repo | Role |
+|------|------|
+| **StepFi-API** (this repo) | Backend — auth/JWT, orchestration, indexing, jobs |
+| [StepFi-Contracts](https://github.com/StepFi-app/StepFi-Contracts) | Soroban smart contracts (credit, reputation, liquidity) |
+| [StepFi-App](https://github.com/StepFi-app/StepFi-App) | Learner mobile client (Expo / React Native) |
+| [StepFi-Web](https://github.com/StepFi-app/StepFi-Web) | Sponsor / vendor / mentor web app |
+| [StepFi-Docs](https://github.com/StepFi-app/StepFi-Docs) | Protocol documentation |
-However, due to dependencies on other service images, we cannot guarantee that schema migrations, seed.sql, and generated types will always work for the same CLI major version. If you need such guarantees, we encourage you to pin a specific version of CLI in package.json.
+## 🏅 Contributors
-## Developing
+
+
-To run from source:
+## 📄 License
-```sh
-# Go >= 1.22
-go run . help
-```
+Released under the [MIT License](./LICENSE).
diff --git a/docs/architecture.svg b/docs/architecture.svg
new file mode 100644
index 0000000..a6e3ffd
--- /dev/null
+++ b/docs/architecture.svg
@@ -0,0 +1,115 @@
+
- ```sh
- brew install supabase/tap/supabase
- ```
+