Tri-Model Personality Backend

Private, owner-scoped backend for the Bazi + MBTI + Zodiac interpretation experience.

Requirements

• Node.js 24+
• One configured frontend origin
• Optional OpenAI key and model for live explanations

Start

npm install
Copy-Item .env.example .env
npm start

The example environment uses SQLite at ./data/profiles.sqlite. Without .env, the service binds to 127.0.0.1:3000 and uses memory storage.

Run the complete verification suite:

npm test

Run the frontend against the local API in a second terminal:

npm run frontend:dev

The Vite proxy keeps BACKEND_ACCESS_TOKEN outside the browser bundle. Set VITE_EXPLANATION_MODE=dry_run in frontend/.env when verifying the follow-up flow without a live model; the default is live.

Frontend Entry Point

Use POST /api/experience/start for the primary product flow. It returns:

• the complete public profile;
• the stable presentation-stage vocabulary;
• deterministic comparison output;
• an optional dry-run or live explanation result.

See API contract, UI integration examples, and runbook.

Privacy And Deployment

• The default host is loopback-only.
• Non-loopback hosting requires a bearer token of at least 32 characters.
• Profile access is scoped by APP_OWNER_ID.
• CORS uses an explicit origin allowlist; wildcard origins are rejected.
• SQLite and export files contain private birth and explanation data. Do not commit or serve them publicly.
• For a browser deployment, keep the bearer token behind a same-origin server-side proxy instead of compiling it into frontend JavaScript.

Current Calendar Basis

The default lunar_javascript_cn provider calculates Jie Qi boundaries for Asia/Shanghai civil time. It does not apply longitude-based true-solar-time correction. Every profile returns calendar_basis so the frontend can disclose this limitation.

This product is a reflective interpretation tool, not a scientific diagnosis, factual identity proof, or event-prediction service.