# 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.