Relationship Milestones

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service File: backend/src/services/relationship.service.ts
Model: backend/src/models/asoState.model.ts

---

Overview

The Relationship Milestones system allows the AI Director to flag significant narrative moments, which are permanently recorded and displayed to the user, providing a tangible sense of progression and depth in the player's personal relationship with the ASO.

---

Architecture

Relationship Flag System

---

Relationship Flags

Storage

Location: aso_states.relationshipFlags (JSONB field)

Format:

{
  "milestone_1": true,
  "shared_secret": "The secret about...",
  "trust_level": 5,
  "first_kiss": "2025-01-15T10:30:00Z"
}

Flag Types

Boolean Flags:

• is_trusted - Player has gained ASO's trust
• first_meeting - First interaction completed
• quest_master - Completed first quest

String Flags:

• shared_secret - Secret shared between player and ASO
• favorite_memory - ASO's favorite memory with player

Numeric Flags:

• trust_level - Trust level (0-10)
• intimacy_level - Intimacy level (0-10)

Date Flags:

• first_kiss - Timestamp of first kiss
• anniversary - Relationship anniversary date

---

Relationship Service

Key Functions

setRelationshipFlag(userId, flag, value)

• Sets relationship flag in ASO state
• Stores in aso_states.relationshipFlags JSONB field
• Creates timeline event
• Returns updated flags

getRelationshipFlags(userId)

• Retrieves all relationship flags for user
• Returns formatted flags object

---

AI Director Integration

Setting Flags

Tool Command:

{
  "setRelationshipFlag": {
    "flag": "is_trusted",
    "value": true
  }
}

Process:

1. AI Director detects significant moment
2. Calls relationshipService.setRelationshipFlag()
3. Flag stored in ASO state
4. Timeline event created
5. Flag displayed to user

---

Timeline Integration

Relationship Events

Event Type: relationship_milestone

Event Data:

{
  "eventType": "relationship_milestone",
  "eventText": "Player gained Yexian's trust",
  "metadata": {
    "flag": "is_trusted",
    "value": true
  }
}

---

Display to User

User Profile

Location: User profile page

Display:

• List of all relationship flags
• Milestone descriptions
• Achievement badges
• Relationship progression timeline

---

Source Files

Primary Sources:

• backend/src/services/relationship.service.ts - Relationship management
• backend/src/models/asoState.model.ts - ASO state model

---

Related Documentation

• AI Director - Relationship flag commands
• Timeline System - Relationship milestone events
• 02-CORE-SYSTEMS/Authentication-Authorization.md - User profiles
• 06-ARCHITECTURE/Database-Schema.md - ASO state storage
• 00-OVERVIEW.md - Complete system overview