Institutional-grade equity research for retail investors.
Finari is a ticker-first equity research platform for US-listed stocks. It turns SEC filings, normalized XBRL facts, filing metadata, source-linked event headlines, and optional AI memos into a plain-English and Thai research screen for retail investors.
The product goal is Bloomberg Terminal + Morningstar + SEC filing analysis + AI, with a consumer-simple interface. Finari is educational research software. It does not provide buy/sell recommendations, price targets, stock-price predictions, or personalized investment advice.
- Public ticker research for US-listed companies.
- English and Thai locale routes at
/enand/th;/redirects by cookie or browser language. - SEC-backed company snapshot, latest financial filing, annual trends, quarterly/TTM trends, balance-sheet analysis, peer comparison, and data-quality caveats.
- Decision screen with strongest evidence, main risk, metric to watch, latest financial filing, and confidence label.
- Statement charts for revenue/net income, cash flow, and balance sheet.
- Latest events and potential financial impact from RSS snippets and SEC filing metadata, with provider-ready architecture.
- Public deterministic memos and event impact reads for anonymous users.
- Private AI memos and private event impact analysis for signed-in users.
- Admin-published canonical public AI memos and event impact analysis.
- Email magic-link authentication, saved research, watchlists, waitlist capture, and S&P 500 ticker selection/backfill.
- Next.js App Router 16, React 19, TypeScript, Tailwind CSS 4
- Recharts for financial visualizations
- Auth.js / NextAuth email magic links with Drizzle adapter
- Drizzle ORM and explicit Postgres migrations
- Railway Postgres for durable application, research, event, auth, and waitlist data
- Railway Redis for short-lived cache, rate-limit state, and refresh locks
- SEC EDGAR JSON APIs for ticker mapping, submissions, and company facts
- RSS event provider by default, with environment placeholders for future licensed news providers
- OpenAI API for server-side AI generation when configured
- Vitest, Testing Library, ESLint, TypeScript, and Gitleaks
Finari v1 is fundamentals-first and source-linked.
- SEC ticker mapping resolves ticker to CIK.
- SEC submissions identify filings and primary filing links.
- SEC company facts supply normalized US-GAAP financial facts.
- RSS feeds supply headline/snippet-level latest event context.
- SEC filing metadata is also treated as an event source.
Finari does not scrape full news articles. Event analysis uses only headlines, feed summaries, source metadata, SEC filing metadata, and deterministic or AI analysis grounded in those inputs.
Finari intentionally excludes these from v1:
- Live stock prices
- Valuation multiples
- Buy/sell/hold recommendations
- Price targets
- Personalized investment advice
- Full article scraping
- User-provided OpenAI API keys or ChatGPT subscription OAuth
OpenAI usage is Finari-managed and server-side through OPENAI_API_KEY. Anonymous users do not trigger OpenAI spend; they receive deterministic public analysis or admin-published public AI analysis.
Copy .env.example to .env.local and set local values:
SEC_USER_AGENT="Finari/0.1 (research app; contact=you@example.com)"
DATABASE_URL="postgres://user:password@localhost:5432/finari"
REDIS_URL="redis://localhost:6379"
NEWS_PROVIDER="rss"
NEWS_RSS_URL_TEMPLATE="https://feeds.finance.yahoo.com/rss/2.0/headline?s={ticker}®ion=US&lang=en-US"
NEWS_API_KEY=""
AUTH_SECRET="replace-with-a-long-random-secret"
AUTH_URL="http://localhost:3000"
FINARI_INVITATION_ONLY="false"
FINARI_INVITED_EMAILS=""
ALERTS_CRON_SECRET="replace-with-a-long-random-secret"
REFRESH_CRON_SECRET="replace-with-a-long-random-secret"
EMAIL_FROM="Finari <research@example.com>"
RESEND_API_KEY=""
OPENAI_API_KEY=""
OPENAI_MODEL="gpt-4.1-mini"
ADMIN_EMAILS="admin@example.com"
FMP_API_KEY=""
FMP_BASE_URL="https://financialmodelingprep.com/stable"Important notes:
SEC_USER_AGENTshould include a real contact address for SEC fair-access compliance.DATABASE_URLis required for durable data.REDIS_URLis optional for local development, but recommended for cache and lock behavior.AUTH_SECRETmust be a long random value in production.AUTH_URLandNEXTAUTH_URLshould both behttps://www.finari.coin production so magic-link callbacks stay on the custom domain.- Finari production access is email magic-link based; any valid email can request a link. Keep
ADMIN_EMAILSlimited to trusted operators. ALERTS_CRON_SECRETmust match the GitHub Actions secret used 8000 by the scheduled alert-delivery workflow.REFRESH_CRON_SECRETmust match the GitHub Actions secret used by the scheduled research-refresh workflow.ACTIVITY_CRON_SECRETmust match the GitHub Actions secret used by the scheduled activity-pruning workflow.ACTIVITY_LOG_RETENTION_DAYSdefaults to180; activity logs store hashed IP/user-agent values and sanitized metadata only.EMAIL_FROMmust use a sender domain verified by the email provider.RESEND_API_KEYis required for production magic-link delivery.OPENAI_API_KEYis optional; without it, Finari returns deterministic fallback memos and event analysis.ADMIN_EMAILSis a comma-separated list of signed-in Finari emails that can publish canonical public analysis.
Requirements:
- Node.js 24+
- pnpm 9+
- Postgres
- Redis, optional but recommended
Install and run:
pnpm install
pnpm db:migrate
pnpm devThe app starts on http://localhost:3000 unless the port is occupied.
For non-technical users on Windows, macOS, or Linux who want everything ready with one command:
pnpm bootstrap:one-clickThis single command:
- Installs dependencies
- Runs migrations
- Starts Finari if not already running
- Warm-loads all S&P 500 ticker analyses into your local database
- Shuts down the temporary local server when done
Before running it, make sure .env.local is set with DATABASE_URL and SEC_USER_AGENT.
For a fully cloned repo where you want all current ticker analyses available immediately, run:
# In one terminal: start the app
pnpm dev
# In another terminal: run full S&P 500 bootstrap
pnpm bootstrap:repobootstrap:repo runs migrations (if needed) and then warms all S&P 500 company snapshots in a conservative pace.
The database schema is managed by Drizzle migrations in drizzle/.
pnpm db:generate
pnpm db:migrate
pnpm db:studioCore durable tables include:
- Auth:
users,accounts,sessions,verification_tokens,user_profiles - Companies and filings:
companies,company_tickers,filings - Financial data:
financial_facts,financial_periods - Research:
research_snapshots,research_memos,research_refresh_runs - Events:
company_events,event_impacts - Product data:
watchlists,watchlist_items,saved_research,alert_preferences,alert_deliveries,waitlist_leads - Audit and cost control:
ai_usage_events
Redis is used only for short-lived cache, rate-limit state, and refresh locks. Do not store durable research or user data in Redis.
The intended Railway topology is:
web: Next.js appPostgres: durable databaseRedis: cache and locks
Use Railway reference variables for private service networking:
DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}Recommended web service settings:
- Pre-deploy command:
pnpm db:migrate - Start command:
pnpm start - Serverless/App Sleeping can be enabled for the web service
- Postgres and Redis should remain durable infrastructure services
- Keep OpenAI, Resend, auth, and database credentials only in Railway variables
Do not commit Railway project IDs, environment IDs, service IDs, public database URLs, API keys, or tokens.
Public routes:
GET /api/search?q=GET /api/sp500GET /api/company/[ticker]GET /api/company/[ticker]/events?locale=en|thPOST /api/company/[ticker]/memo?locale=en|thPOST /api/waitlist
Authenticated user routes:
GET /api/mePOST /api/me/company/[ticker]/memo?locale=en|thPOST /api/me/company/[ticker]/events/analysis?locale=en|thGET /api/research/savedPOST /api/research/savedGET /api/watchlistsPOST /api/watchlistsPOST /api/watchlists/[id]/itemsGET /api/watchlists/[id]/itemsGET /api/alertsPOST /api/alertsPATCH /api/alerts/[id]GET /api/alerts/deliveriesPATCH /api/alerts/deliveries/[id]GET /api/valuation/[ticker]GET /api/workspace/export
Admin routes:
POST /api/admin/company/[ticker]/memo?locale=en|thPOST /api/admin/company/[ticker]/events/refresh?locale=en|thPATCH /api/admin/company/[ticker]/events/[eventId]POST /api/admin/alerts/deliver(admin session orAuthorization: Bearer <ALERTS_CRON_SECRET>for scheduled delivery)
Admin authorization is based on the signed-in user's email matching ADMIN_EMAILS.
The alert-delivery route also accepts the cron secret so GitHub Actions can trigger it automatically on a schedule.
Finari can warm and persist research snapshots for the current S&P 500 constituent list. The script calls the app's existing API one ticker at a time, so normal persistence stores companies, filings, normalized periods, facts, snapshots, citations, and optional event impacts.
Dry-run the ticker list:
pnpm backfill:sp500 -- --dry-runSmoke-test a small run:
FINARI_BASE_URL=https://your-finari-domain.example pnpm backfill:sp500 -- --limit 5 --delay-ms 2500Run the full S&P 500 backfill conservatively:
FINARI_BASE_URL=https://your-finari-domain.example pnpm backfill:sp500 -- --delay-ms 3000 --max-failures 25Or use the new shorthand bootstrap script:
pnpm bootstrap:sp500Run bootstrap against a deployment or different locale by passing any standard backfill flags:
FINARI_BASE_URL=https://your-finari-domain.example pnpm bootstrap:sp500 -- --locale th --include-eventsResume after the last successful ticker from the JSONL report:
FINARI_BASE_URL=https://your-finari-domain.example pnpm backfill:sp500 -- --start-after MSFT --delay-ms 3000Useful options:
--include-eventsalso warms event impact cards.--locale thwarms optional event reads in Thai.--tickers AAPL,MSFT,NVDAlimits the run to explicit tickers.--ticker-file ./tickers.txtreads tickers from a file.--output .data/backfill.jsonlwrites a JSONL report.
Public AI memos are not generated by the backfill script.
Run the local verification suite before opening or merging changes:
pnpm lint
pnpm typecheck
pnpm test
pnpm buildSecurity scans:
pnpm security:secrets
pnpm security:secrets:currentGitHub Actions currently run:
ci: lint, typecheck, tests, and buildGitleaks: full git-history and checked-out file secret scanningalert-delivery: scheduledPOST /api/admin/alerts/delivertrigger usingALERTS_CRON_SECRETdaily-research-refresh: scheduledpnpm backfill:sp500trigger usingREFRESH_CRON_SECRET
For the scheduled alert-delivery workflow:
- Set the repository variable
FINARI_BASE_URLto the deployed app URL. - Set the repository secret
ALERTS_CRON_SECRETto the same value used by the app runtime. - If either value is missing, the workflow logs a warning and skips delivery instead of failing the scheduled run.
For the scheduled research-refresh workflow:
- Set the repository variable
FINARI_BASE_URLto the deployed app URL. - Set the repository secret
REFRESH_CRON_SECRETto the same value used by the app runtime.
Finari supports English and Thai.
/enrenders the English product experience./threnders the Thai product experience./redirects by saved locale preference, then browser language, then English fallback.- Source names, company names, ticker symbols, SEC forms, filing links, and published headlines remain as source data.
- Finari-generated UI labels, summaries, deterministic analysis, fallback memos, prompts, disclaimers, and errors should be localized through
src/lib/i18n.ts.
Before making the repository public or accepting external contributions:
- Keep
.env*files out of git. - Keep Railway, OpenAI, Resend, database, Redis, and auth secrets only in environment variables.
- Run
pnpm security:secretsbefore publishing sensitive branches. - Keep GitHub secret scanning and Gitleaks enabled.
- Avoid hardcoding production domains, project IDs, service IDs, or private infrastructure details in docs or code.
- Review generated files before committing; browser artifacts and local
.data/reports should not be committed.
This codebase uses protected main with pull requests and required checks. Keep changes focused, add or update tests for behavior changes, and preserve the educational research boundary: no recommendations, no price targets, and no personalized advice.