# RapportArc — Product Design Specification

**Version:** 1.0  
**Status:** Proposal  
**Product:** RapportArc — Specialized LLM-Assisted Social Fluency Training

---

## 1. Executive summary

RapportArc is a subscription digital product: a single-page application (SPA) through which learners complete guided training paths in romantic and social fluency. The platform combines structured lessons, assessments, **cached long-form responses**, **LLM-evaluated qualitative exams**, **interactive multimodal drills** (image, text, optional video), and a **persona-conditioned conversational simulator** (“girlfriend simulator”) so users can rehearse realistic threads across scenarios (cold contact, warmed lead, professional context, post-date texting, long-term rapport).

Differentiation is **specialization**: not generic “communication tips,” but a sequenced curriculum, measurable progress, historical feedback, and practice against consistent, tunable personas.

---

## 2. Product vision and positioning

| Element | Definition |
|--------|------------|
| **Mission** | Help adults build respectful, attractive, context-aware rapport—from first impression through sustained romantic connection—using deliberate practice, feedback, and simulation. |
| **Vision** | A trusted training environment where progress is visible, feedback is personalized, and practice feels safe and repeatable. |
| **Positioning** | Premium, specialized coursework plus AI-augmented coaching; not a dating app and not therapy. |

---

## 3. Guiding principles and ethics

- **Consent and respect** are modeled in content and in simulator behavior; training avoids coercion, harassment, or dehumanizing framing. Playful “creative association” drills use **fictional, absurd, or obviously humorous** prompts to unlock spontaneity—not to encourage judgment of real individuals.
- **Clear boundaries**: marketing and in-product copy state that the product is educational and that users remain responsible for real-world behavior and local norms.
- **Data minimization**: store only what is needed for progress, feedback history, and compliance; encrypt sensitive text at rest where feasible.
- **LLM safety**: server-side prompts enforce rubrics, refusal policies, and escalation paths for harmful content in user submissions.

---

## 4. Target users

| Segment | Needs |
|--------|--------|
| **Socially fluent but inconsistent** | Wants repeatable drills and feedback on text and “openers.” |
| **Career-focused adults** | Limited time; wants clear modules and progress tracking. |
| **Post-app or hybrid daters** | Wants texting and date-follow-up playbooks and practice. |

---

## 5. Core user journeys

1. **Onboard** → account creation → course catalog → enroll in a track.
2. **Learn** → modules (video/text/image) → short checks → progress saved.
3. **Assess** → multiple-choice / multi-select / dropdown exams → scored; optional retakes per policy.
4. **Qualitative exam** → long answer draft autosaved → submit → LLM pipeline returns structured feedback → history retained.
5. **Interactive drill** → stimulus (e.g. image + prompt) → user response → optional light scoring or LLM comment.
6. **Simulator** → choose scenario + persona profile → multi-turn chat → debrief or score.
7. **Dashboard** → charts for scores, sentiment or rubric dimensions over time, submission history.

---

## 6. System architecture (logical)

```
┌─────────────────────────────────────────────────────────────────┐
│                        Client SPA (browser)                      │
│  Auth UI · Course shell · Forms · Drills · Charts · Simulator UI │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTPS / JSON
┌────────────────────────────▼────────────────────────────────────┐
│                      API layer (BFF or REST)                     │
│  Sessions · Courses · Progress · Submissions · Simulator threads   │
└─────┬──────────────────┬────────────────────┬──────────────────┘
      │                  │                    │
      ▼                  ▼                    ▼
┌─────────────┐  ┌───────────────┐   ┌──────────────────┐
│  Identity   │  │  Primary DB   │   │  Object storage  │
│  (OAuth/    │  │  (users,      │   │  (media, large   │
│   OIDC)     │  │   enrollments,│   │   artifacts)     │
│             │  │   drafts,     │   │                  │
│             │  │   attempts)   │   │                  │
└─────────────┘  └───────┬───────┘   └──────────────────┘
                         │
                         ▼
                 ┌───────────────┐
                 │  Job queue    │
                 │  (async LLM)  │
                 └───────┬───────┘
                         ▼
                 ┌───────────────┐
                 │ LLM pipeline  │
                 │ (rubrics,     │
                 │  feedback,    │
                 │  simulator)   │
                 └───────────────┘
```

---

## 7. Major components

| Component | Responsibility |
|-----------|----------------|
| **SPA shell** | Routing, layout, authenticated vs public routes, design system. |
| **Auth & identity** | Login, sessions, password reset, optional SSO; user id as foreign key everywhere. |
| **Course engine** | Course → module → lesson graph; prerequisite rules; unlock logic. |
| **Progress service** | Lesson completion, exam attempts, time-on-task; idempotent updates. |
| **Assessment forms** | Radio, checkbox groups, dropdowns, validation; scoring keys versioned per exam. |
| **Draft & submit service** | Autosave for long text (debounced); versioning; submit locks or re-submit policy per exam. |
| **LLM pipeline** | Input: prompt template + rubric + user text + optional context. Output: structured JSON (scores, bullets, next steps). Async jobs + retries; cost controls. |
| **Feedback history store** | Append-only or versioned records per submission; links to rubric version. |
| **Analytics & dashboard** | Aggregate metrics per user; chart data API; export optional. |
| **Simulator engine** | Thread state; persona system prompt + scenario parameters; turn limits; safety filters. |
| **Media pipeline** | Signed URLs for images/video; optional transcoding; alt text for accessibility. |
| **Admin (phase 2)** | Course authoring, rubric editor, prompt versioning, moderation queue. |

---

## 8. Data model (conceptual)

- **User**, **Profile** (preferences, timezone).
- **Course**, **Module**, **Lesson** (type: content | quiz | qualitative | drill | simulator).
- **Enrollment**, **LessonProgress** (status, last position, completed_at).
- **ExamDefinition**, **ExamAttempt** (answers, score, attempt number).
- **TextSubmission** (draft body, submitted body, timestamps, exam id).
- **FeedbackRecord** (submission id, model id, rubric version, structured feedback JSON, raw model output optional).
- **SimulatorSession**, **SimulatorMessage** (role, content, metadata).
- **AuditLog** (admin actions, prompt version changes).

---

## 9. Curriculum structure (example tracks)

Multiple **courses** can share the simulator and rubric engine; examples:

1. **Foundations** — context reading, tone, boundaries, creative association drills.
2. **Messaging arc** — pre-primed threads → bolder openings → user sends first message; forward progression to rapport, ask-out, stall/tension when date is far; post-date etiquette.
3. **Long-term** — push-pull, novelty, consistent romance without neediness.

Each module mixes **content**, **quizzes**, **qualitative exams**, and **simulator scenarios** aligned to learning objectives.

---

## 10. Non-functional requirements

- **Performance:** P95 < 300ms for CRUD APIs; LLM jobs async with clear UI states.
- **Availability:** Target 99.5% for core APIs in production.
- **Security:** OWASP ASVS-aligned; secrets in vault; rate limits on auth and LLM endpoints.
- **Accessibility:** WCAG 2.1 AA targets for learner UI.
- **Observability:** Structured logs, traces for LLM calls, metrics for queue depth and failure rates.

---

## 11. Roadmap (indicative)

| Phase | Scope |
|-------|--------|
| **MVP** | Auth, one course, quizzes, one qualitative pipeline, basic dashboard, one simulator persona. |
| **V1** | Full draft cache, multiple courses, drill templates, chart library, persona library. |
| **V2** | Admin authoring, A/B rubrics, moderation, mobile-optimized PWA. |

---

## 12. Open decisions

- **Hosting:** Cloud provider and managed DB vs self-hosted.
- **Models:** Single vendor vs fallback; fine-tuning vs prompt-only.
- **Pricing:** Subscription tiers, seat limits, trial length.

---

*This specification is a product and engineering blueprint for RapportArc under Visionary Software Solutions.*