Folionix
A system for your portfolio.
Self-hosted wealth command center — IDX stocks, gold, mutual funds, and bonds in one place. Watches the market continuously, runs local LLM analysis, sends Telegram alerts, and serves a Next.js dashboard. Your server, your data.
Project page: marvello.xyz/folionix
What It Does
A unified wealth tracker across four asset classes — IDX stocks, gold, mutual funds, and bonds — with LLM-powered analysis for stocks and a clean dashboard for everything.
yahoo-finance2 ──┐
Cermati (gold) ──┼──▶ Postgres ──▶ Ollama ──▶ Telegram alerts
Cermati (funds)──┤ └──▶ Next.js dashboard
KSEI (bonds) ──┘
Stocks (IDX)
- Fetches real-time prices via yahoo-finance2, Finnhub fallback
- Runs per-position LLM analysis (Ollama) with news sentiment context
- Sends Telegram alerts: BUY / HOLD / MONITOR / CUT LOSS
- Tracks watchlist with BUY NOW / WAIT / AVOID verdicts
- Signal-aware LangGraph orchestrator monitors during market hours
- Optional multi-agent deep runs on major signals: deterministic analyst scores + up to 12 LLM investor personas (Buffett, Burry, …) voting into a weighted consensus, processed async via a Postgres job queue
Gold
- Tracks purchases per venue (Cermati GraphQL)
- Values holdings at venue sell-back price (not buy price)
- Bot commands:
/gadd, /glist, /gremove, /gprice
Mutual Funds
- Sweeps Cermati NAV feed — no per-fund calls needed
- Values holdings at latest NAV per unit
fund_catalog powers web autocomplete for adding positions
Bonds (Retail: SR / ORI / SBR / ST)
- Valued at par/principal — no price feed
- KSEI coupon schedule sync
- Tracks days to maturity
Dashboard
- Next.js 16 + Tailwind — Stocks, News, Gold, Funds, Bonds, Reviews
- All CRUD via centered modal dialogs; reads/writes Postgres directly through its own pool, behind NextAuth
Quick Start
Prerequisites
- Node 22+ (both backend and frontend)
- Ollama running locally with a model (default:
qwen2.5:7b)
- Telegram bot token (create one)
- Postgres 17 — shipped as the
folionix-db compose service; see the Postgres foundation runbook for bootstrap steps
1. Clone & Configure
git clone https://github.com/Marvello/Folionix.git
cd Folionix
cp .env.example .env
# Edit .env: DATABASE_URL (backend + web share it), AUTH_SECRET,
# LLM_BACKEND/LLM_MODEL/LLM_API_BASE, TELEGRAM_TOKEN, TELEGRAM_CHAT_ID
2. Stand Up Postgres
docker compose -f docker/docker-compose.yml up -d folionix-db
psql "$DATABASE_URL" -f db/schema.sql
# then db/migrations/037_*.sql onward, in numeric order
# (schema.sql already contains migrations 001-036 — do not replay them)
Create your single user by inserting a row into public.users with a bcrypt
password_hash — there is no public sign-up. Optionally pre-load
db/seed.sql for starter positions and watchlist.
3. Set Up Portfolio
Positions and watchlist live in Postgres (the source of truth) — add them via the
Telegram bot (/add BBCA 9500 10, /wadd TLKM) or the web UI.
Note: 1 lot = 100 shares. Tickers use IDX codes without .JK suffix.
4. Run
With Docker (recommended) — brings up the database alongside the services:
docker compose -f docker/docker-compose.yml up -d
Without Docker:
# Backend
cd app && npm install
npm run portfolio # full portfolio analysis + Telegram alerts
npm run prices # price-only refresh (no LLM)
npm run prices -- BBCA TLKM # specific tickers
npm run watchlist # watchlist analysis
npm run bot # Telegram bot (long-polling)
npm run graph # LangGraph orchestrator (long-running, signal-aware)
npm run worker # multi-agent analysis worker (drains analysis_jobs)
# Frontend
cd web && npm install && npm run dev # http://localhost:3000
Project Structure
app/ # Node 22 TypeScript backend (ESM, esbuild)
├── src/
│ ├── db/db.ts # Postgres data layer (node-postgres)
│ ├── providers/ # market.ts (yahoo-finance2), finnhub.ts, cermati.ts, ksei.ts
│ ├── ai/ # llm.ts (Vercel AI SDK), prompts.ts, scores.ts, personas.ts, consensus.ts
│ ├── services/ # portfolio.ts, news.ts, watchlist.ts, gold.ts, funds.ts, bonds.ts
│ ├── telegram/ # client.ts, alerts.ts
│ ├── bot/bot.ts # grammy Telegram bot (14 commands)
│ └── graph/ # LangGraph orchestrator (state/session/signals/analysis/orchestrator/runner) + worker.ts (deep-run queue)
lib/ # Shared TypeScript (app/ + web/)
├── types.ts # Postgres row interfaces
└── format.ts # Shared helpers (fmtIdr, calcPnl, normalizeTicker, …)
web/ # Next.js + Tailwind frontend (App Router)
├── app/ # routes: /, /portfolio, /watchlist, /news, /gold, /funds, /bonds, /login
├── components/ # Nav, MetricCard, RecommendationBadge, modals
└── lib/ # format.ts, types.ts, db.ts (pg pool), auth.ts (NextAuth)
db/ # Postgres schema, migrations, seed
docker/ # Dockerfile.app, Dockerfile.web, docker-compose.yml
Docker Services
| Service | Purpose | Port |
|---|
folionix-graph | LangGraph orchestrator (session-aware, signal-driven) | — |
folionix-bot | Telegram bot (long-polling) | — |
folionix-worker | Multi-agent analysis worker (drains analysis_jobs) | — |
folionix-web | Next.js + Tailwind dashboard | 3000 |
folionix-bot/folionix-graph/folionix-worker use marvellooni/folionix-app:latest; folionix-web uses marvellooni/folionix-web:latest.
NEXT_PUBLIC_* env vars are read at runtime (injected via window.__ENV) — the image is environment-agnostic.
Postgres runs as the folionix-db compose service with a pgdata volume. Containers run as non-root.
Pin a specific deploy with FOLIONIX_TAG=<sha8> docker compose -f docker/docker-compose.yml up -d.
Telegram Bot Commands
| Command | Description |
|---|
/status | Current portfolio P&L summary |
/detail BBCA | Detailed analysis for a ticker |
/add BBCA 9500 10 | Record a BUY (ticker, price, lots) in the transaction ledger |
/remove BBCA | Hide position (reappears on its next transaction) |
/analyze BBCA | Trigger on-demand LLM analysis |
/portfolio | Export portfolio as JSON |
/accuracy | Recommendation backtest results |
/wadd TLKM [notes] | Add ticker to watchlist |
/wremove TLKM | Remove ticker from watchlist |
/wlist | Show current watchlist |
/gadd · /glist · /gremove · /gprice | Gold position management |
/flist | List fund holdings (read-only) |
/blist | List bond holdings (read-only) |
Configuration
Non-secret tunables (signal/alert thresholds, SEND_TELEGRAM, recommendation & AI
options incl. LLM_MODEL, and schedules) can be changed at runtime on the web
Settings page — no redeploy; runner, worker and bot pick changes up within a minute.
A value saved there overrides .env; "Reset to default" falls back to .env. Each
setting is explained on that page (source: lib/settings.ts).
| Variable | Description |
|---|
DATABASE_URL | Postgres connection string — read by both app/ and web/; server-side only |
AUTH_SECRET / AUTH_URL | NextAuth session signing and base URL (web) |
LLM_BACKEND | ollama, or openai for any OpenAI-compatible gateway |
LLM_MODEL | LLM model name (e.g. qwen2.5:7b) |
LLM_API_BASE | LLM API endpoint |
LLM_API_KEY | LLM API key (if required) |
TELEGRAM_TOKEN / TELEGRAM_CHAT_ID | Bot token and allowed chat ID whitelist |
SEND_TELEGRAM | true/false — enable/disable Telegram alerts |
CACHE_MINUTES | Skip re-fetch if data is fresh (default: 30) |
FINNHUB_API_KEY | Optional; enables Finnhub fallback when yahoo-finance2 fails |
CERMATI_GRAPHQL_URL | Cermati gold-price GraphQL endpoint |
CERMATI_MF_URL | Cermati mutual-fund products REST endpoint |
SIGNAL_PRICE_MINOR / SIGNAL_PRICE_MAJOR | Price move % thresholds (default: 3.0 / 5.0) |
SIGNAL_VOLUME_MINOR / SIGNAL_VOLUME_MAJOR | Volume ratio thresholds (default: 1.5 / 3.0) |
SIGNAL_COOLDOWN_MIN | Minutes before re-analyzing same ticker (default: 15) |
GRAPH_ACTIVE_INTERVAL / GRAPH_IDLE_INTERVAL | Orchestrator check intervals in seconds |
DEEP_RUNS_ENABLED | true routes MAJOR signals to multi-agent deep runs (default: false) |
PERSONAS | Enabled investor personas — comma list of names or a number = first N (default: all 12) |
Monitoring Schedule
The LangGraph orchestrator (folionix-graph) replaces cron with adaptive, signal-aware scheduling:
| Session (WIB) | Behavior |
|---|
| 08:45–09:00 (Pre-market) | Signal check, prepare ticker list |
| 09:00–11:30 (Session 1) | Active monitoring, signal detection |
| 11:30–13:30 (Lunch) | Signal check only; major signals trigger immediate analysis |
| 13:30–15:00 (Session 2) | Active monitoring, signal detection |
| 15:00–15:30 (After hours) | Final analysis pass |
| 15:30–08:45 (Closed) | No analysis |
Signal-driven: Price moves >3% or volume spikes >1.5x trigger additional analysis. Major signals (>5% price, >3x volume) trigger immediate analysis regardless of schedule — and, with DEEP_RUNS_ENABLED=true, enqueue a multi-agent deep run (deterministic analyst scores → persona votes → weighted consensus) drained asynchronously by folionix-worker.
Tech Stack
- Data: yahoo-finance2 (primary), Finnhub (fallback), Cermati (gold + funds), KSEI (bond coupons)
- LLM: Vercel AI SDK — Ollama or any OpenAI-compatible gateway (any model)
- Orchestration: @langchain/langgraph (session-aware, signal-driven)
- Database: self-hosted Postgres 17 via node-postgres (raw SQL, no ORM)
- Bot: grammy (Telegram, long-polling)
- UI: Next.js 16 + Tailwind (
web/)
- CI/CD: GitHub Actions → Docker Hub (multi-arch: amd64 + arm64)
License
This project is licensed under the PolyForm Noncommercial License 1.0.0: free to use, modify, and share for any noncommercial purpose. Commercial use requires a separate paid license — contact [email protected].
