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].