Neon-Desk/docs/REBUILD_DECISIONS.md

Fiscal Clone Rebuild Decisions

This document records the ground-up design choices for the 2026 rebuild so every major decision is explicit and reviewable.

1) Architecture: split frontend and API

• Decision: keep Next.js in frontend/ and a dedicated high-throughput API in backend/.
• Why: clean separation for scaling and deployment; web rendering and data ingestion do not contend for resources.
• Tradeoff: more services to run locally.

2) Runtime choice: Bun + Elysia for API

• Decision: use Bun runtime with Elysia for low overhead and fast cold/warm request handling.
• Why: strong performance profile for IO-heavy workloads (quotes, SEC fetch, queue polling).
• Tradeoff: narrower ecosystem compatibility than plain Node in some libraries.

3) Auth standard: Better Auth only

• Decision: use Better Auth end-to-end and remove legacy JWT/NextAuth patterns.
• Why: single auth surface across API and Next.js clients, DB-backed sessions, less custom auth code.
• Tradeoff: schema must align closely with Better Auth expectations.

4) Persistence: PostgreSQL as source of truth

• Decision: keep Postgres for all domain entities and task durability.
• Why: transactional consistency, mature operational tooling, simple backup/restore.
• Tradeoff: queue throughput is lower than specialized brokers at massive scale.

5) Long-running jobs: durable DB queue

• Decision: implement a durable long_tasks queue table plus dedicated worker process.
• Why: supports multi-minute jobs, retries, result persistence, and survives API restarts.
• Tradeoff: custom queue logic is more code than dropping in a broker library.

6) Async-first API for heavy workflows

• Decision: filing sync, filing analysis, and portfolio insights are queued and polled via /api/tasks/:id.
• Why: avoids request timeouts and keeps the UX responsive.
• Tradeoff: frontend must handle job lifecycle states.

7) AI integration contract for OpenClaw/ZeroClaw

• Decision: use an adapter that targets an OpenAI-compatible chat endpoint (OPENCLAW_BASE_URL) with model override (OPENCLAW_MODEL).
• Why: works with OpenClaw/ZeroClaw deployments while keeping provider lock-in low.
• Tradeoff: advanced provider-specific features are not exposed in v1.

8) SEC ingestion strategy

• Decision: fetch filings from SEC submissions API and enrich with company facts metrics.
• Why: stable machine-readable endpoints with less brittle parsing than HTML scraping.
• Tradeoff: facts can lag specific filing publication timing.

9) Market pricing strategy

• Decision: use Yahoo Finance chart endpoint for quote snapshots and periodic refresh.
• Why: good coverage and straightforward integration for portfolio mark-to-market.
• Tradeoff: endpoint reliability/quotas can vary; provider abstraction retained for future switch.

10) API shape: domain modules + strict schemas

• Decision: organize routes by domain (portfolio, watchlist, filings, ai, tasks) with Zod-style schema validation via Elysia types.
• Why: predictable contract boundaries and safer payload handling.
• Tradeoff: slight boilerplate cost.

11) Security posture

• Decision: all business endpoints require authenticated session resolution through Better Auth session API.
• Why: prevents cross-user data access and removes implicit trust in client-supplied user IDs.
• Tradeoff: each protected route performs auth/session checks.

12) Frontend rendering model

• Decision: use Next.js App Router with client-heavy dashboards where live polling is required.
• Why: server rendering for shell + interactive client zones for real-time task/market updates.
• Tradeoff: more client-side state management in dashboard screens.

13) Design language: terminal-futurist UI system

• Decision: build a clear terminal-inspired design with grid scanlines, mono + geometric type pairing, and neon cyan/green accent palette.
• Why: matches requested futuristic terminal aesthetic while remaining readable.
• Tradeoff: highly stylized branding may not fit conservative enterprise environments.

14) Performance defaults

• Decision: optimize for fewer round trips (batched fetches), async processing, indexed SQL, and paginated list endpoints.
• Why: improves p95 latency under concurrent load.
• Tradeoff: slightly more complex query/service code.

15) Operations model

• Decision: run three processes in production: frontend, backend API, backend worker.
• Why: isolates web traffic from heavy background processing and enables independent scaling.
• Tradeoff: additional deployment/health-check wiring.