App Developer Docs

Setup & Running

The app is split into two processes: a Hono backend (port 3001) and a Vite dev server for the Vue frontend (port 5173). In development you run both; in production the backend serves the built frontend as static files.

Prerequisites

• Node.js 20+
• An OpenAI API key
• (Optional) SMTP credentials for real magic-link emails — in development, links are printed to the terminal

First-time setup

# 1 — Install backend dependencies
cd backend
npm install

# 2 — Configure environment
cp .env.example .env
# Open .env and at minimum set:
#   OPENAI_API_KEY=sk-...
#   OPENAI_MODEL=gpt-4o-mini   (or whatever current model you want)

# 3 — Install frontend dependencies
cd ../frontend
npm install

Running in development

From the repo root:

./dev.sh

This starts both processes. Frontend hot-reloads are proxied transparently through Vite to the backend on port 3001.

Or run them separately in two terminals:

# Terminal 1
cd backend && npm run dev

# Terminal 2
cd frontend && npm run dev

Open http://localhost:5173.

Magic links in development

Real SMTP is not required locally. When NODE_ENV is not production, the backend logs the magic link URL directly to the terminal instead of sending an email:

[dev] Magic link for you@email.com :
 http://localhost:3001/api/auth/magic?token=abc123...

Click that URL in your terminal to complete sign-in.

Running the test suites

# Backend (21 integration tests)
cd backend && npm test

# Frontend (25 component tests)
cd frontend && npm test

Tests use an in-memory SQLite database and mock both email sending and OpenAI calls — no environment variables required.

Production build

cd frontend && npm run build       # outputs to frontend/dist/
cd ../backend && NODE_ENV=production npm start

The backend serves frontend/dist/ as static files and handles all /api/* routes. A single process on a single port.

Environment variables

All variables live in backend/.env. See backend/.env.example for the full list.