What PIE is
PIE (Personal Investment Engine) is a self-hosted dashboard for tracking funds, accounts, allocation vs targets, India (NRE / MF / FD), tax reminders, and optional AI summaries. Data stays on your Postgres unless you configure outbound email or AI APIs.
Database & hosting
PIE uses a single Postgres database configured in .env as
DATABASE_URL.
When you host on a VPS, nothing is copied automatically. Your local data remains on
your machine until you migrate it (for example pg_dump from local and
pg_restore on the server, or managed Postgres import). If you point the VPS
DATABASE_URL at an empty database, you get a fresh empty PIE — your old
data is not “lost”, it simply was never transferred. Always take a backup before changing URLs or
providers.
Navigation
The sidebar groups Workspace (day-to-day numbers) and Intelligence (research / AI / reports). Settings holds allocation targets, IMAP, notifications, integrations, health checks, and destructive actions such as portfolio reset.
Overview & portfolio math
Overview aggregates holdings (with cashflows), active accounts, FX rates, and optional India mutual funds to compute net worth, MoM change, allocation vs equity/bonds/cash targets, XIRR from cashflows, confidence and health scores. NAV freshness and FX staleness feed into those scores.
Portfolio is the detailed holdings grid; edits flow through the API to the same models Overview reads.
This month & planner
This month ties to the allocation planner: planned buys/sells/holds, SIP rows, and execution status. Logic respects tax-free windows and persona/risk settings merged from AppSettings and legacy Settings.
India
India views combine NRE/NRO-style accounts, mutual fund positions, and FD ladders with RBI reference rates and DTAA-style helpers where implemented. FX conversion uses the same rate table as the rest of the dashboard.
Email ingestion
Optional IMAP (legacy Settings fields today) fetches bank/fund emails, parses previews,
and can auto-create SIP executions when confidence is high and auto-ingest is enabled. PIE does not delete
mail on the server. Integrations include comms.imap for future consolidation and tests.
Integrations (V5.2)
comms.smtp— outbound mail (Gmail OAuth via API or classic SMTP + app password).comms.telegram— bot token + your numeric chat id for alerts and slash commands.comms.imap— optional duplicate path for IMAP tests.ai.*— API keys for Ask PIE; exactly one AI provider is “active” in AppSettings.fx.exchangerate-api— optional FX provider key.
Secrets are encrypted at rest; the Settings UI masks saved values until you paste a replacement.
Settings & alerts
Allocation targets, theme, risk profile, alert email, Telegram chat id, monthly letter and alert toggles live here (merged with AppSettings where applicable). Send test email uses configured SMTP/OAuth. System health runs checks against DB, integrations, and jobs.
Ask PIE (AI)
The intelligence view sends portfolio context and your question to the configured AI provider. It is optional; without keys, that area stays disabled. AI debug logs can be toggled in App Settings.
Backtest & patterns
Backtest Lab runs historical scenarios against stored or imported series; Patterns surfaces recurring behaviours from past data where implemented. Both read from the same Postgres models as the rest of PIE.
Health & cron
Scheduled jobs (morning digest, pruning, FX refresh, etc.) record rows in CronExecution and
SystemHealth. The health grid on Settings and Overview reflects recent checks.
Portfolio fresh start (danger)
Under Settings → Data & backups, Reset portfolio truncates almost
all personal data tables on DATABASE_URL while keeping
Settings, AppSettings, IntegrationProvider, and the seeded
InstrumentLibrary. You must type reset to confirm. Take a pg_dump backup
first if there is anything you might regret losing.
Dashboard login
Turn Dashboard login on under Settings → App preferences (stored as
AppSettings.dashboardAuthEnabled). The browser must then sign in; the password is stored
(bcrypt) on AppSettings. First-time setup on /login.html accepts the bootstrap phrase from
Settings (stored hashed) or PIE_AUTH_BOOTSTRAP_KEY from .env.
Set PIE_DASHBOARD_AUTH=0 in .env
only to force login off if you lock yourself out. Session cookies are signed with
SESSION_SECRET. Forgot-password emails use your saved Alert email and
require working outbound mail. Gmail OAuth redirect URLs are documented on the SMTP integration card.
This page is a concise manual, not every line of code. For migration notes and sprint maps, see the
docs/ folder in the repository.