Audio XX
A listener-driven suggestion engine for thoughtful hi-fi system building.
Status (2026-05-09): active development on the friends branch; pre-public-beta. The deterministic reasoning engine is production-quality; an LLM overlay for unknown-product handling is planned but not yet wired. See docs/PROJECT_STATE.md for an honest current-state assessment.
Documentation
Operational and architectural documentation lives in docs/. Recommended reading order for a new contributor:
The locked behavioural specification lives in CLAUDE.md at the repository root.
Philosophy
Audio XX is built on three core principles:
Listener-First
User listening impressions and constraints drive the system. Specs, rankings, and popularity never override listener context. The system reasons about what you hear, not what a reviewer measured.
Trait-First Reasoning
The system reasons in terms of listening traits (flow, clarity, composure, dynamics, etc.) and trade-offs. Components are levers that move traits — they are not the object of reasoning.
Regression-Aware Guidance
The system prioritizes protecting existing strengths. It avoids changes that risk degrading traits the listener already values. "Do nothing" is a valid and sometimes correct outcome. Maximum 1–2 suggestions per evaluation. Always includes trade-offs, risks, and a controlled next step.
Getting Started
Prerequisites
- Node.js 20+ (TODO: verify — no
engines field declared in package.json. Project has been developed on Node 20+; older versions are not tested.)
- npm 10+
Quick setup
npm install
cd apps/web
npx prisma generate
npx prisma db push
npm run db:seed
cd ../..
npm run dev
The app runs at http://localhost:3000. New accounts are created automatically on first sign-in.
For environment variables, database options (local SQLite vs. production Turso), and troubleshooting, see docs/SETUP.md.
Common commands (from repo root)
| Command | Purpose |
|---|
npm run dev | Start the Next.js dev server on port 3000 |
npm run build | Production build (runs prisma generate first) |
npm test | Vitest test suite (~134 test files) |
npm run typecheck | TypeScript checking across apps/web and packages/rules |
npm run lint | ESLint across .ts / .tsx |
npm run db:generate | Regenerate Prisma client |
npm run db:push | Push Prisma schema to local DB |
npm run db:seed | Seed reference components from YAML |
Branch strategy
| Branch | Role |
|---|
main | Stable. Reserved for journalist-readiness tier. The default branch on GitHub. |
friends | Active development. All recent work ships here. Deploys automatically to a Vercel preview environment. |
eval-baseline, pre-fix-backup, safety/before-deploy-sync, wip-save-audio-xx, fix/system-state | Historical / backup branches. Treat as read-only. |
Day-to-day work happens on friends. Each logical change ships as an isolated commit. Merging friends → main is gated on the milestone definitions in ROADMAP-SPEAKS-FOR-ITSELF.md and docs/ROADMAP.md.
Rule Editing Guide
Rules are stored in packages/rules/rules.yaml. Each rule has:
- id: unique-rule-id
label: Human-readable label
priority: 10 # Lower = higher priority
conditions:
symptoms_present: # All must be present
- symptom_name
symptoms_present_any: # At least one must be present
- symptom_a
- symptom_b
symptoms_absent: # None may be present
- symptom_c
traits: # Trait direction requirements
fatigue_risk: up
archetypes_include: # User must have these archetypes
- engagement
has_improvement_signals: true # Boolean
archetype_conflict: true # Boolean
outputs:
explanation: >
Prose explanation of what the system inferred.
suggestions:
- Maximum 1-2 suggestions
risks:
- Trade-off or risk description
next_step: >
A reversible, practical next step.
verdict: no_purchase_recommended # Optional
archetype_note: > # Optional
Note for specific archetypes.
To add a new rule, add a YAML entry to the rules array. No code changes required. The rule engine loads rules at evaluation time.
Signal Dictionary Guide
The signal dictionary maps listener phrases to trait signals. It is stored in packages/signals/signals.yaml.
Each entry maps trigger phrases to trait directions and symptom labels:
- phrases:
- bright
- harsh
- sibilant
signals:
fatigue_risk: up
glare_risk: up
symptom: brightness_harshness
archetype_hint: composure # Optional
Uncertainty markers are also defined in this file. When free text contains markers like "maybe", "not sure", or "I think", the system increases conservatism — narrower suggestions, stronger preference for "do nothing."
To add a new phrase mapping, add an entry to the signals array. No code changes required.
Seed Data Guide
Component seed data is in packages/data/components.yaml. Each component entry includes:
id: Unique identifiername, brand, category: Basic infoconfidence_level: high, medium-high, medium, or lowrole_confidence: For multi-function components (e.g., { dac: high, preamp: low })trait_tendencies: Map of trait → qualitative value (strong, moderate, slight, neutral, slight-risk, moderate-risk)risk_flags: Array of known riskstrusted_references: Sources of knowledge about this componentreviews: Contextual only — reviews inform explanations, they do not decide outcomesis_reference: Whether this is a reference component (non-commercial)user_submitted: Whether this was entered by a user
To add a new seed component, add a YAML entry. Run npm run db:seed to load it into the database.
Reference systems are in packages/data/reference-systems.yaml. These are non-commercial anchors used to explain listening trade-offs, not to sell products.
Reference System Transparency
Some reference systems use equipment that is no longer made or not sold through commercial partners. These systems are included to explain listening trade-offs, not to sell products.
Reference systems are clearly distinguished from commercial suggestions:
- "Reference system (non-commercial)"
- "Shares some traits with" — never "This is the same as"
- "Moves the system in a similar direction"
- "Captures part of the same behavior"
Affiliate and Outbound Links Policy
Audio XX may include outbound or affiliate links to help users explore availability of suggested components. These links do not influence suggestions or evaluations.
Suggestions are generated independently of retailers, pricing, or affiliate relationships. In many cases, Audio XX may recommend delaying a purchase or making no purchase at all.
Evaluations of used-market listings or user-submitted components are not monetized.
Architecture
/apps/web ← Next.js frontend + API routes
/packages/rules ← Rule engine logic + rules.yaml
/packages/data ← Seed components + reference systems YAML
/packages/signals ← Signal dictionary YAML + phrase-to-trait mapping
Three-Layer Pipeline
System assessments flow through three layers with strict separation of concerns.
Reasoning Engine — The deterministic analysis pipeline. Parses system chains, infers component traits from product catalog and brand profiles, synthesises system-level axes via role-weighted voting, detects bottlenecks, stacked biases, and synergies, and ranks upgrade paths. This layer is the source of truth. All analytical conclusions originate here. Key files: consultation.ts, axis-types.ts, intent.ts, product catalogs under products/.
Memo Generation — Translates reasoning output into a structured MemoFindings contract and then into a ConsultationResponse. Assembles structured data (system chain, component verdicts, upgrade paths, keep recommendations) and pre-computed prose fields into a unified response object. An optional LLM overlay (memo-llm-overlay.ts) can refine prose asynchronously while the deterministic output is shown immediately. Key files: memo-findings.ts, memo-deterministic-renderer.ts, advisory-response.ts.
Presentation Layer — Formats the memo response into a 9-section system review. Controls section ordering, narrative tone, and visual rendering. Does not contain reasoning logic. Key files: AdvisoryMessage.tsx, AdvisoryComponentAssessments.tsx, AdvisoryUpgradePaths.tsx.
The 9-section review structure: (1) System Overview, (2) Current System Chain, (3) What the System Does Especially Well, (4) Trade-offs in the System, (5) Strength of Each Component, (6) Upgrade Paths, (7) Components I Would Keep, (8) Recommended Upgrade Path, (9) System Philosophy Insight.
Each layer has a clear boundary. The reasoning engine never touches presentation. The presentation layer never performs analysis. The memo generation layer assembles but does not reason. When making changes, identify which layer owns the concern and modify only that layer.
Data Flow
- User enters free text describing listening impressions
- Signal processor maps phrases → trait signals, symptoms, archetype hints
- Rule engine evaluates symptoms + traits + archetypes against YAML rules
- Matching rules produce explanations, suggestions (max 2), risks, and next steps
- Result is saved as a preference snapshot and displayed with full transparency
Key Constraints
- Deterministic: no ML, no hidden embeddings
- Maximum 1–2 suggestions per evaluation
- "No purchase recommended" is a first-class output
- Reviews inform explanations; they never decide outcomes
- Archetype conflicts are surfaced, never silently resolved
Multi-System Support
Each user has one listener profile and can define multiple audio systems.
A system represents a physical setup — a speaker rig in a living room, a
headphone desk, an office system — and consists of named components with
brand, category, and optional role metadata.
Data model:
- One listener profile per user (stored in the
Profile table).
Contains listening preferences, room context, archetype signals, and a
reference to the currently active system.
- Multiple systems per user (stored in the
System table via
User.systems). Each system carries a name, location, primary use,
tendencies summary, and a component list via the SystemComponent
junction table.
active_system_id on the listener profile selects which system
the advisory engine operates against. Nullable — having no active
system is a valid state.
Advisory flow:
The active system is resolved once per submit using
resolveActiveSystemContext() and optionally converted into a
SystemProfile via activeSystemToProfile(). Advisory builders and the
reasoning pipeline receive this context as an optional parameter.
When present, the active system seeds component context, informs chain
interaction analysis, and provides a baseline for system diagnosis.
When absent, builders fall back to conversation-derived context.
Guest support:
Unauthenticated users work with a single draft system persisted to
sessionStorage. It participates in advisory flows identically to a
saved system. On sign-in, saved systems load from the backend; the
draft is preserved until explicitly promoted or cleared.
Conversation extraction:
When a user describes owned gear in conversation ("I have a…", "my
system is…"), the engine detects the description and offers to save it
as a new system. Detection is conservative — it requires ownership
language, rejects comparison and shopping patterns, requires at least
two recognized components, and suppresses duplicates of the active
system via fingerprint overlap.
Testing
npm test
Tests cover:
- Low-volume listener warnings and prioritization
- Reference system non-commercial framing
- "No purchase recommended" output
- Archetype conflict explicit trade-off language
- Uncertainty marker conservatism
- Free text affecting inferred traits and rule outcomes
- Rule output constraints (max suggestions, required risks/next steps)
