Align codebase with the V1 production brief
Reconciles the implementation against the final MVP brief:
- Data model: rename users.provider to auth_provider and
users.subscription_status to subscription, matching the brief's schema
exactly (id, email, auth_provider, subscription, created_at). External
API field names are unchanged.
- Suggestions: replace the starter list with the brief's eight examples.
- Instructions: personality updated to calm, warm, intelligent, curious,
respectful, pedagogical — never judging, manipulative, dramatic,
overly positive, overconfident or preaching. Added per-reply goals:
feel personal, be calm, instill safety, give hope without promising
results, deepen thinking, and always contain at least one genuinely
new thought or question. Added the conversation outcome goal (greater
clarity, greater calm, a new perspective, increased trust in one's own
ability) and 'not a chatbot for general questions' to positioning.
- Paywall transition example updated to the brief's wording ('I'm
starting to see some recurring patterns… Unlock Premium to continue.').
- Knowledge base completed per the brief: communication models
(perceptual positions, observation vs interpretation, chunking,
backtracking, boundaries), reflection exercises (meaning audit,
meta-question, five frames, observer replay, well-formed outcome,
evening question) and a question library organized by purpose.
Appreciation in the Lift step must be anchored in what the user
actually expressed; the Challenge step never preaches.
- README: product principle (one user, one conversation, one analysis,
one recommendation), the removal rule, design words per the brief,
Definition of Done (7 steps), V2 not-now list (journal, saved
insights, community, coaches, courses, voice), and a closed-beta plan
for 20-50 testers with what the minimal data model can already
measure.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0118DaxZR36RpnY524vRqx3z
This commit is contained in:
@@ -28,9 +28,13 @@ and the stores must follow the same rule.
|
||||
**Tone.** Never judging, dramatic, overenthusiastic, or preaching. Always
|
||||
calm, curious, clear, respectful, structured, thoughtful.
|
||||
|
||||
**Design.** Scandinavian, clinical, quiet, precise, minimal. Off-white
|
||||
background, near-black text, one dark blue-green accent. Generous white
|
||||
space. No animations, no gradients.
|
||||
**Design.** Clinical, Scandinavian, quiet, intelligent, premium, minimal.
|
||||
Off-white background, near-black text, one dark blue-green accent. Generous
|
||||
white space. No animations, no gradients. The rule: if something can be
|
||||
removed without reducing user value, remove it.
|
||||
|
||||
**Product principle.** One user. One conversation. One analysis. One
|
||||
recommendation. That is the whole product.
|
||||
|
||||
## System overview
|
||||
|
||||
@@ -57,8 +61,11 @@ it is not built.
|
||||
users use `POST /chat` with a **Cognito** JWT (Apple / Google / email via
|
||||
the hosted UI).
|
||||
3. The Lambda calls the **OpenAI Responses API** with the Markdown knowledge
|
||||
base (`services/api/knowledge/`) as system instructions. The model
|
||||
returns structured output: a reply plus an `analysis_ready` flag.
|
||||
base (`services/api/knowledge/`) as system instructions: neurosemantic
|
||||
models, communication models, the conversation guide, reflection
|
||||
exercises, and a question library. V1 invests in prompt design quality,
|
||||
not infrastructure complexity. The model returns structured output: a
|
||||
reply plus an `analysis_ready` flag.
|
||||
4. Sign-in happens at the paywall, since a purchase must attach to an
|
||||
account. Usage counters live in **PostgreSQL** (Aurora Serverless v2).
|
||||
|
||||
@@ -86,7 +93,7 @@ abuse backstop for the free tier — it is not the paywall.
|
||||
|
||||
Conversations are never stored server-side; the client holds them in memory
|
||||
and sends the running transcript with each request. The database stores the
|
||||
absolute minimum: `users` (id, email, provider, subscription_status,
|
||||
absolute minimum: `users` (id, email, auth_provider, subscription,
|
||||
created_at) and `usage` (messages_used, last_reset). No profiling, no
|
||||
training on user data. Error logging is anonymized (no message content).
|
||||
|
||||
@@ -193,12 +200,33 @@ API Gateway, Lambda, Cognito, S3, Secrets Manager and CloudWatch — and V1
|
||||
does not even need S3. No Redis, no Kubernetes, no Kafka, no Elasticsearch,
|
||||
no queues, no microservices. One backend. Maximal simplicity.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Version 1 is done when a user can:
|
||||
|
||||
1. Open the app.
|
||||
2. Start a conversation immediately.
|
||||
3. Feel seen and understood.
|
||||
4. Receive a number of well-considered follow-up questions.
|
||||
5. Reach a natural premium boundary.
|
||||
6. Buy Premium.
|
||||
7. Continue the conversation.
|
||||
|
||||
If a feature does not help the user reflect better, it is not built.
|
||||
Version 1 must be small, fast, stable, and easy to maintain.
|
||||
|
||||
## Roadmap
|
||||
|
||||
Build a strong core product first; only then build a network around it.
|
||||
Build a strong core product first; only then build around it.
|
||||
|
||||
- **Version 1 (this repo)** — Person ↔ Semantika. Nothing else.
|
||||
- **Version 2** — Person ↔ Semantika ↔ small reflection groups.
|
||||
- **Version 3** — certified coaches, live sessions, study circles, courses.
|
||||
- **Version 2 (not now)** — journal, saved insights, community, certified
|
||||
coaches, courses, voice conversations. None of these are built in V1.
|
||||
|
||||
Community features are deliberately absent from V1.
|
||||
**Next step: a closed beta.** Put V1 in the hands of 20–50 test users
|
||||
before adding anything. The minimal data model already answers several of
|
||||
the key questions — how many come back (`usage.last_reset` vs activity),
|
||||
how deep dialogues go (`messages_used`), and when users upgrade
|
||||
(`subscription` transitions). Which starter questions create the most value
|
||||
requires asking testers directly, since conversations are never stored.
|
||||
Anything beyond that must justify itself against the privacy rule.
|
||||
|
||||
Reference in New Issue
Block a user