Financial Graph

A knowledge graph application for exploring corporate structures, subsidiaries, and business relationships using SEC filing data.

🚀 Quick Start

Prerequisites

• Node.js 24+ (see .nvmrc)
• Bun package manager
• Google Cloud Platform account (for authentication)

1. Clone and Install

git clone <repository-url>

cd /home/bun/Documents/Repo/financial-graph/shared
bun install
bun run build

cd ../backend
bun install
bunx playwright install chromium

pipx runpip marker-pdf install \
--upgrade \
--force-reinstall \
torch torchvision torchaudio \
--index-url https://download.pytorch.org/whl/cu124

2. Set up Google OAuth Authentication

The application uses Google OAuth for secure authentication.

1. Follow the detailed setup guide: https://www.instantdb.com/docs/auth/google-oauth?method=web-google-button

2. Configure environment variables:

   # Repo root
   cp .env.example .env
   # Edit .env and add your Google Client ID + Resend settings

3. Start Development

# Start frontend
cd frontend
bun run dev

# Start backend (in another terminal)
cd backend
bun run dev

Visit http://localhost:5173 and sign in with Google.

🔐 Authentication

Features

• Google OAuth Integration: Secure authentication using Google accounts
• Session Management: Persistent sessions with profile display (sign-in/out handled via InstantDB auth hooks)

🏗️ Architecture

Frontend (/frontend)

• React 19 with TypeScript
• Vite for development and building
• InstantDB for real-time data and authentication
• Tailwind CSS for styling

Backend (/backend)

• Node.js with TypeScript
• SEC filing parsers for extracting corporate data
• InstantDB for data storage
• LLM integration for data enrichment and fallbacks
• Jobs & pipelines for SEC data ingest:
  • See job details in backend/README.md.

Shared (/shared)

• Common types and utilities
• InstantDB schema definitions
• Validation logic

📊 Features

Corporate Structure Visualization

• Interactive graphs showing parent-subsidiary relationships
• Jurisdiction mapping with geographic visualization
• Treemap views for hierarchical data exploration
• Search functionality for finding specific companies

Data Sources

• SEC Exhibit 21 filings (subsidiary lists)
• SEC company metadata (CIK, tickers, names)
• S&P 500 company classifications
• Jurisdiction normalization (ISO country codes)

Advanced Features

• Real-time collaboration via InstantDB
• Mobile-responsive design
• Keyboard shortcuts for power users
• Export capabilities (CSV, Excel)

🛠️ Development

Project Structure

financial-graph/
├── frontend/          # React application
├── backend/           # Node.js API and parsers
├── shared/            # Common code and types
├── docs/              # Documentation
└── tools/             # Development utilities

Key Commands

# Install dependencies
bun install

# Development
bun run dev          # Start frontend
cd backend && bun run dev  # Start backend

# Building
bun run build        # Build frontend
cd backend && bun run build  # Build backend

# Testing
bun run test         # Run tests

Environment Variables

Frontend + API (root .env)

VITE_INSTANTDB_APP_ID=your-instantdb-app-id
VITE_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
VITE_GOOGLE_CLIENT_NAME=google-web

RESEND_API_KEY=your-resend-api-key
CONTACT_SENDER_EMAIL=notifications@yourdomain.com
CONTACT_TO_EMAIL=you@yourdomain.com

Backend (backend/.env)

INSTANTDB_ADMIN_TOKEN=your-instantdb-admin-token
# Additional backend configuration...

📚 Documentation

• Google OAuth Setup - Complete authentication setup guide
• Project Documentation - Technical documentation and architecture
• API Documentation - Backend API reference
• Data Sources - Information about SEC filing formats

🔧 Troubleshooting

Authentication Issues

1. "redirect_uri_mismatch": Check Google Cloud Console redirect URIs
2. "invalid_client": Verify Google Client ID in environment variables
3. Session not persisting: Check browser localStorage and console errors

Development Issues

1. Port conflicts: Frontend runs on 5173, backend on 3000
2. CORS errors: Ensure backend is running and accessible
3. Build failures: Check Node.js version (requires 24+)

Getting Help

1. Check browser console for error messages
2. Review the setup guides in /docs
3. Test authentication with window.authTest utilities
4. Check InstantDB dashboard for data and auth logs

🚀 Deployment

Production Setup

1. Configure production OAuth credentials
2. Set production environment variables
3. Build and deploy frontend
4. Deploy backend services
5. Configure InstantDB for production

See SETUP.md for setup and deployment instructions.

📄 License

[License information]

🤝 Contributing

[Contributing guidelines]

---

Last Updated: January 2026 Authentication: Google OAuth Status: Active development