136 lines
2.8 KiB
Markdown
136 lines
2.8 KiB
Markdown
# Fiscal Clone 2.0
|
|
|
|
Ground-up rebuild of a `fiscal.ai`-style platform with:
|
|
- Better Auth for session-backed auth
|
|
- Next.js frontend
|
|
- high-throughput API service
|
|
- durable long-running task worker
|
|
- OpenClaw/ZeroClaw AI integration
|
|
- futuristic terminal UI language
|
|
|
|
## Feature Coverage
|
|
|
|
- Authentication (email/password via Better Auth)
|
|
- Watchlist management
|
|
- SEC filings ingestion (10-K, 10-Q, 8-K)
|
|
- Filing analysis jobs (async AI pipeline)
|
|
- Portfolio holdings and summary analytics
|
|
- Price refresh jobs (async)
|
|
- AI portfolio insight jobs (async)
|
|
- Task tracking endpoint and UI polling
|
|
|
|
## Architecture
|
|
|
|
- `frontend/`: Next.js App Router UI
|
|
- `backend/`: Elysia API + Better Auth + domain routes
|
|
- `backend/src/worker.ts`: durable queue worker
|
|
- `docs/REBUILD_DECISIONS.md`: one-by-one architecture decisions
|
|
|
|
Runtime topology:
|
|
1. Frontend web app
|
|
2. Backend API
|
|
3. Worker process for long tasks
|
|
4. PostgreSQL
|
|
|
|
## Local Setup
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### 1) Backend
|
|
|
|
```bash
|
|
cd backend
|
|
bun install
|
|
bun run db:migrate
|
|
bun run dev
|
|
```
|
|
|
|
### 2) Worker (new terminal)
|
|
|
|
```bash
|
|
cd backend
|
|
bun run dev:worker
|
|
```
|
|
|
|
### 3) Frontend (new terminal)
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Frontend: `http://localhost:3000`
|
|
Backend: `http://localhost:3001`
|
|
Swagger: `http://localhost:3001/swagger`
|
|
|
|
## Docker Compose
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
This starts: `postgres`, `backend`, `worker`, `frontend`.
|
|
|
|
## Coolify
|
|
|
|
Deploy using the root compose file and configure separate public domains for:
|
|
- `frontend` on port `3000`
|
|
- `backend` on port `3001`
|
|
|
|
Use the full guide in `COOLIFY.md`.
|
|
|
|
Critical variables for Coolify:
|
|
- `FRONTEND_URL` = frontend public URL
|
|
- `BETTER_AUTH_BASE_URL` = backend public URL
|
|
- `NEXT_PUBLIC_API_URL` = backend public URL (build-time in frontend)
|
|
|
|
## Core API Surface
|
|
|
|
Auth:
|
|
- `ALL /api/auth/*` (Better Auth handler)
|
|
- `GET /api/me`
|
|
|
|
Watchlist:
|
|
- `GET /api/watchlist`
|
|
- `POST /api/watchlist`
|
|
- `DELETE /api/watchlist/:id`
|
|
|
|
Portfolio:
|
|
- `GET /api/portfolio/holdings`
|
|
- `POST /api/portfolio/holdings`
|
|
- `PATCH /api/portfolio/holdings/:id`
|
|
- `DELETE /api/portfolio/holdings/:id`
|
|
- `GET /api/portfolio/summary`
|
|
- `POST /api/portfolio/refresh-prices` (queues task)
|
|
- `POST /api/portfolio/insights/generate` (queues task)
|
|
- `GET /api/portfolio/insights/latest`
|
|
|
|
Filings:
|
|
- `GET /api/filings?ticker=&limit=`
|
|
- `GET /api/filings/:accessionNumber`
|
|
- `POST /api/filings/sync` (queues task)
|
|
- `POST /api/filings/:accessionNumber/analyze` (queues task)
|
|
|
|
Task tracking:
|
|
- `GET /api/tasks`
|
|
- `GET /api/tasks/:taskId`
|
|
|
|
## OpenClaw / ZeroClaw Integration
|
|
|
|
Set these in `.env`:
|
|
|
|
```env
|
|
OPENCLAW_BASE_URL=http://localhost:4000
|
|
OPENCLAW_API_KEY=...
|
|
OPENCLAW_MODEL=zeroclaw
|
|
```
|
|
|
|
The backend expects an OpenAI-compatible `/v1/chat/completions` endpoint.
|
|
|
|
## Decision Log
|
|
|
|
See `docs/REBUILD_DECISIONS.md` for the detailed rationale and tradeoffs behind each major design choice.
|