# 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