feat: Complete Fiscal Clone deployment package

- SEC filings extraction (10-K, 10-Q, 8-K) - Portfolio analytics with real-time prices - Watchlist management - NextAuth.js authentication - OpenClaw AI integration - PostgreSQL database with auto P&L calculations - Elysia.js backend (Bun runtime) - Next.js 14 frontend (TailwindCSS + Recharts) - Production-ready Docker configurations
2026-02-16 03:49:32 +00:00
commit da58289eb1
39 changed files with 4070 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,367 @@
+# 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
+
+```bash
+# 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
+
+```env
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+```sql
+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
+```sql
+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)
+```sql
+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
+```sql
+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
+- [x] User authentication (GitHub, Google, Email/Password)
+- [x] SEC EDGAR data scraping
+- [x] Key metrics extraction from filings
+- [x] Stock holdings tracking
+- [x] Real-time price updates (Yahoo Finance)
+- [x] Automatic P&L calculations
+- [x] Portfolio value summary
+- [x] Gain/loss tracking with percentages
+- [x] Portfolio allocation pie chart
+- [x] Performance line chart
+- [x] Watchlist management
+- [x] Add/delete holdings
+- [x] Add/remove stocks from watchlist
+- [x] OpenClaw AI integration endpoints
+- [x] Database migrations with triggers
+- [x] Full CRUD operations
+- [x] Responsive design
+- [x] Loading states
+- [x] User feedback
+- [x] 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