Neon-Desk/README.md

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

cp .env.example .env

1) Backend

cd backend
bun install
bun run db:migrate
bun run dev

2) Worker (new terminal)

cd backend
bun run dev:worker

3) Frontend (new terminal)

cd frontend
npm install
npm run dev

Frontend: http://localhost:3000
Backend: http://localhost:3001
Swagger: http://localhost:3001/swagger

Docker Compose

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:

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.