Francy51/Neon-Desk
2
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da58289eb1b6d26fc2d851dbff093cc222933901
Neon-Desk/README.md
Francesco da58289eb1 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

368 lines
9.4 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink