ARCHITECTURE.md

Qdecision Architecture

Qdecision is intentionally small in surface area but opinionated in flow. The project is optimized around one thing: turning a vague Chinese decision problem into a compact judgment experience.

Core Flow

1. The user enters a raw decision question on /
2. The app creates a DecisionSession
3. The server runs:
   • classify
   • generateQuestions
4. The user answers 2 to 4 clarifying questions on /analyze
5. The server generates:
   • quick for the first judgment
   • full for the final narrative and future paths
6. The result page merges both into a single presentation flow

Main Modules

UI

• src/app/ Next.js App Router pages and API routes
• src/components/home/ Home input and onboarding experience
• src/components/chat/ Analyze flow and question UI
• src/components/result/ Result narrative, action, boundary, and future path visualization

Domain Logic

• src/lib/decision/ Intake validation, decision pipeline, normalization, fallback logic, report generation, and repository access
• src/lib/llm/ Provider routing, prompt construction, structured parsing, repair, and telemetry

Persistence

• prisma/schema.prisma DecisionSession and Feedback
• prisma/dev.db Default local SQLite database

Design Choices

Local-first by default

The default setup assumes Ollama and SQLite. This keeps the project easy to run, demo, and modify on a single machine.

Structured outputs everywhere

LLM outputs are validated by Zod before entering the rest of the system. If parsing fails, the app tries to repair the JSON once before falling back.

Fast first, deep second

The app does not wait for the full report before becoming useful. It first generates a quick tilt, then enriches it with the full report and future path tree.

Anonymous browser ownership

Sessions are scoped by the qdecision_viewer_id cookie so local history remains isolated without forcing authentication.