Fiscal Clone

Financial filings extraction and portfolio analytics powered by SEC EDGAR.

Features

• SEC Filings Extraction

  • 10-K, 10-Q, 8-K filings support
  • Key metrics extraction (revenue, net income, assets, cash, debt)
  • Real-time search and updates

• Portfolio Analytics

  • Stock holdings tracking
  • Real-time price updates (Yahoo Finance API)
  • Automatic P&L calculations
  • Performance charts (pie chart allocation, line chart performance)

• Watchlist Management

  • Add/remove stocks to watchlist
  • Track company and sector information
  • Quick access to filings and portfolio

• Authentication

  • NextAuth.js with multiple providers
  • GitHub, Google OAuth, Email/Password
  • JWT-based session management with 30-day expiration

• OpenClaw Integration

  • AI portfolio insights
  • AI filing analysis
  • Discord notification endpoints

Tech Stack

• Backend: Elysia.js (Bun runtime)
• Frontend: Next.js 14 + TailwindCSS + Recharts
• Database: PostgreSQL with automatic P&L calculations
• Data Sources: SEC EDGAR API, Yahoo Finance API
• Authentication: NextAuth.js (GitHub, Google, Credentials)
• Deployment: Coolify (Docker Compose)

Getting Started

Prerequisites

• Node.js 20+
• Bun 1.0+
• PostgreSQL 16
• GitHub account
• Coolify instance with API access

Installation

# Clone repository
git clone https://git.b11studio.xyz/francy51/fiscal-clone.git
cd fiscal-clone

# Install backend dependencies
cd backend
bun install

# Install frontend dependencies
cd frontend
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your configuration
nano .env

Environment Variables

# Database
DATABASE_URL=postgres://postgres:your_password@localhost:5432/fiscal
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=fiscal

# Backend
PORT=3001
NODE_ENV=production
JWT_SECRET=your-jwt-secret-key-min-32-characters
GITHUB_ID=your_github_oauth_client_id
GITHUB_SECRET=your_github_oauth_client_secret
GOOGLE_ID=your_google_oauth_client_id
GOOGLE_SECRET=your_google_oauth_client_secret

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:3001

Running Locally

# Run database migrations
cd backend
bun run db:migrate

# Start backend
cd backend
bun run dev

# Start frontend (new terminal)
cd frontend
npm run dev

Deployment via Gitea to Coolify

1. Push to Gitea

# Initialize git
cd /data/workspace/fiscal-clone
git init
git add .
git commit -m "feat: Initial Fiscal Clone release"

# Add remote
git remote add gitea https://git.b11studio.xyz/francy51/fiscal-clone.git

# Push to Gitea
git push -u gitea:your-gitea-username main

2. Deploy to Coolify

In Coolify dashboard:

1. Create Application

   • Type: Docker Compose
   • Name: fiscal-clone
   • Source: Git Repository
   • Repository: git@git.b11studio.xyz:francy51/fiscal-clone.git
   • Branch: main
   • Build Context: /
   • Docker Compose File: docker-compose.yml

2. Configure Domains

   • Frontend: fiscal.b11studio.xyz
   • Backend API: api.fiscal.b11studio.xyz

3. Add Environment Variables

   DATABASE_URL=postgres://postgres:password@postgres:5432/fiscal
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=your-password
   POSTGRES_DB=fiscal
   PORT=3001
   JWT_SECRET=your-jwt-secret
   NEXT_PUBLIC_API_URL=http://backend:3000
   GITHUB_ID=your-github-oauth-id
   GITHUB_SECRET=your-github-oauth-secret
   GOOGLE_ID=your-google-oauth-id
   GOOGLE_SECRET=your-google-oauth-secret
   

4. Deploy

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login
• POST /api/auth/verify - Verify JWT token

SEC Filings

• GET /api/filings - Get all filings
• GET /api/filings/:ticker - Get filings by ticker
• POST /api/filings/refresh/:ticker - Refresh filings

Portfolio

• GET /api/portfolio/:userId - Get portfolio
• GET /api/portfolio/:userId/summary - Get summary
• POST /api/portfolio - Add holding
• PUT /api/portfolio/:id - Update holding
• DELETE /api/portfolio/:id - Delete holding

Watchlist

• GET /api/watchlist/:userId - Get watchlist
• POST /api/watchlist - Add stock
• DELETE /api/watchlist/:id - Remove stock

OpenClaw Integration

• POST /api/openclaw/notify/filing - Discord notification
• POST /api/openclaw/insights/portfolio - Portfolio analysis
• POST /api/openclaw/insights/filing - Filing analysis

Database Schema

Users

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password TEXT NOT NULL,
  name VARCHAR(255),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Filings

CREATE TABLE filings (
  id SERIAL PRIMARY KEY,
  ticker VARCHAR(10) NOT NULL,
  filing_type VARCHAR(20) NOT NULL,
  filing_date DATE NOT NULL,
  accession_number VARCHAR(40) UNIQUE NOT NULL,
  cik VARCHAR(20) NOT NULL,
  company_name TEXT NOT NULL,
  key_metrics JSONB,
  insights TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Portfolio (with auto-calculations)

CREATE TABLE portfolio (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
  ticker VARCHAR(10) NOT NULL,
  shares NUMERIC(20, 4) NOT NULL,
  avg_cost NUMERIC(10, 4) NOT NULL,
  current_price NUMERIC(10, 4),
  current_value NUMERIC(20, 4),
  gain_loss NUMERIC(20, 4),
  gain_loss_pct NUMERIC(10, 4),
  last_updated TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id, ticker)
);

Watchlist

CREATE TABLE watchlist (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
  ticker VARCHAR(10) NOT NULL,
  company_name TEXT NOT NULL,
  sector VARCHAR(100),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id, ticker)
);

Project Structure

fiscal-clone/
├── backend/
│   ├── src/
│   │   ├── index.ts           # Main server
│   │   ├── db/
│   │   │   ├── index.ts    # Database connection
│   │   │   └── migrate.ts  # Database migrations
│   │   ├── routes/
│   │   │   ├── auth.ts      # Authentication
│   │   │   ├── filings.ts   # SEC filings API
│   │   │   ├── portfolio.ts  # Portfolio management
│   │   │   ├── watchlist.ts  # Watchlist management
│   │   │   └── openclaw.ts  # AI integration
│   │   └── services/
│   │       ├── sec.ts         # SEC EDGAR scraper
│   │       └── prices.ts      # Yahoo Finance service
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── package.json
├── frontend/
│   ├── app/
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Dashboard
│   │   ├── auth/
│   │   │   ├── signin/page.tsx   # Login
│   │   │   └── signup/page.tsx   # Registration
│   │   ├── portfolio/page.tsx  # Portfolio management
│   │   ├── filings/page.tsx     # SEC filings
│   │   └── watchlist/page.tsx  # Watchlist
│   ├── lib/
│   │   ├── auth.ts            # Auth helpers
│   │   └── utils.ts           # Utility functions
│   ├── globals.css
│   ├── tailwind.config.js
│   ├── next.config.js
│   ├── tsconfig.json
│   └── package.json
├── docker-compose.yml          # Full stack deployment
└── .env.example               # Environment variables template

Features Status

✅ Implemented

• User authentication (GitHub, Google, Email/Password)
• SEC EDGAR data scraping
• Key metrics extraction from filings
• Stock holdings tracking
• Real-time price updates (Yahoo Finance)
• Automatic P&L calculations
• Portfolio value summary
• Gain/loss tracking with percentages
• Portfolio allocation pie chart
• Performance line chart
• Watchlist management
• Add/delete holdings
• Add/remove stocks from watchlist
• OpenClaw AI integration endpoints
• Database migrations with triggers
• Full CRUD operations
• Responsive design
• Loading states
• User feedback
• Production-ready Docker configs

🚀 Future Enhancements

• WebSocket for real-time stock prices
• Two-factor authentication
• More filing types (S-1, 13D, DEF 14A, etc.)
• PDF parsing for full filing documents
• Export functionality (CSV, PDF)
• Mobile app
• Advanced analytics and reports
• Social features (follow portfolios, share holdings)
• Custom alerts and notifications
• Tax reporting features

Security

• Passwords hashed with bcryptjs
• JWT tokens with 30-day expiration
• Protected routes with session checks
• CORS configured for allowed origins
• SQL injection prevention with parameterized queries
• XSS prevention with proper input sanitization
• HTTPS support (via Coolify proxy)
• Environment variables for sensitive data

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE file for details

Support

For issues or questions:

• Open an issue on Gitea
• Check the documentation
• Contact the maintainers

---

Status: ✅ Production Ready Version: 1.0.0 Last Updated: 2026-02-15