Session Feature: Refined Business & Technical Architecture

---

Executive Summary

This document describes the business and technical architecture for the advanced session feature, including use case-driven AI, phase management, and collaborative task assignment. It integrates the latest refinements and advanced features for a robust, scalable, and user-centric solution.

---

1. Refined Architecture Overview

Business Flow

A session is a collaborative room where users (typically in a group) come together to achieve a specific goal or task. It progresses through four main phases:

1. Ideation: Users share ideas and comments on the session's topic.
2. Approaches: AI generates a single, most suitable approach based on ideation and use case prompts. The approach is chosen specifically to allow many users to contribute through realistic and complementary tasks.
3. Task Generation: Personalized, realistic, and complementary roles/tasks are created based on user answers and AI logic.
4. Task Submission: Each user submits proof of completing their task via content (photo, text, rating, etc.).

Use Case Integration

• Admins can define use cases (title, prompt, category).
• When sessions reach the 'Approaches' phase:
  • System detects the most relevant use case using NLP or similarity matching.
  • The matched prompt is combined with ideation content and fed to AI for better, context-aware strategy generation.

AI Prompt Flow and Smart Contribution

1. Input: Session topic + description + ideation content + matched use case prompt.
2. AI Output: One strongest approach, selected for its potential to involve multiple users in different, complementary roles that help achieve the session's goal.
3. AI Questions: Realistic questions to understand each user's ability, resources, and context (e.g., who has a car, who has money, who is available).
4. Task Assignment: Based on answers, AI generates tailored tasks (e.g., one user buys tickets, another buys popcorn, another drives the group).
5. Content Guidance: Each task includes a clear instruction and what to post (image, review, selfie, etc.) to validate their contribution.

Technical Components

• Session Model: Manages phase, topic, useCaseId.
• Use Case Model: Stores prompts/templates.
• AI Service: Handles prompt generation, task logic, and OpenAI/LLM calls.
• Phase Engine: Transitions session stages, triggers AI processes.
• Task Model: Contains task instructions, user assignment, and content guidance.
• Post Model: Final submissions including media, ratings.
• Notification Service: Alerts for phase changes, task due times.
• Admin Dashboard: Create/manage use cases, view session analytics.

Advanced Features & Enhancements

• Prompt Templates per Use Case: Allow personalized tone/styles.
• Dynamic Role Matching: Users answer questions (budget, skills), AI assigns fitting tasks based on realistic contribution.
• Flexible Phase Config: Customizable phase flows for various session types.
• Analytics: Track engagement, completion rates, quality of AI outputs.
• Secure Roles & Access: Soft deletes, visibility levels, audit trails.
• AI Feedback Loop: Store AI prompts/responses for evaluation and improvement.

---

2. Detailed Business Architecture

Example Use Case: Group Hangout

• Session Topic: "What should we do this weekend?"
• Ideation: Members suggest ideas (cinema, bowling, picnic).
• Approaches: AI, using a relevant use case prompt, suggests a plan (e.g., go to cinema) and realistic roles (buy tickets, buy popcorn, drive, etc.).
• Task Generation: Each user is assigned a role/task (buy tickets, buy popcorn, drive group, etc.) with clear instructions and a call to share results (e.g., post a selfie with tickets, rate popcorn).
• Task Submission: Users post their results, completing the session goal.

Dashboard Use Cases

• Admins can define use cases with titles and prompts.
• When a session is created, it can be linked to a use case.
• During the approach phase, the system queries for similar use cases and uses their prompts to guide AI generation for more relevant, engaging approaches.

---

3. Technical Architecture

Components

• Session Model: Stores session metadata, phase, topic, description, use case reference, etc.
• Use Case Model: Stores reusable use case prompts and metadata.
• AI Service: Handles prompt engineering, context assembly, and calls to LLMs for approach/task generation.
• Phases Engine: Manages phase transitions, triggers AI generation, and schedules notifications.
• Task Model: Stores generated tasks, assignments, and submission status/content.
• Post Model: Stores user submissions (content, images, ratings, etc.).
• Notification Service: Notifies users at key events (phase changes, task assignments, reminders).
• Dashboard/Admin UI: Allows creation and management of use cases, session monitoring, and analytics.

Flow Diagram

graph TD
  A[Session Created] --> B[Ideation Phase]
  B --> C[AI Generate Approaches - use case prompt]
  C --> D[User Selects Approach and Answers Questions]
  D --> E[AI Generate Complementary Tasks and Roles]
  E --> F[Task Assignment]
  F --> G[User Completes Task]
  G --> H[User Submits Post or Content]
  H --> I[Session Goal Achieved]

Loading

AI Integration

• Prompt Selection: On approach phase, system queries for similar use cases and selects the best prompt.
• Context Assembly: Combines session topic, description, ideation content, and use case prompt.
• Approach Generation: AI generates approaches that maximize group contribution and complementarity.
• Task Generation: AI generates realistic, actionable, and content-driven tasks for each user.
• Content Guidance: Each task includes explicit instructions for what to post/share as proof of completion.

Example AI Prompt Flow

1. Input: Use case prompt + session topic/description + ideation content.
2. AI Output: Approaches (e.g., "Go to cinema" with roles/questions).
3. User Input: Selects approach, answers questions.
4. AI Output: Tasks (e.g., "Buy tickets and post a selfie with them").

Data Model Extensions

• Session: Add useCaseId (nullable), phase, etc.
• UseCase: id, title, prompt, tags, etc.
• Task: id, sessionId, profileId, description, instructions, contentGuidance, status, etc.

Notifications

• On phase transitions (ideation end, approach start/end, task assignment).
• On task due soon, task submission reminders.

Security & Scalability

• Role-based access for session creation, use case management.
• Scalable AI service (async jobs, caching, retries).
• Audit logs for session and task activity.

---

4. Required Model and API Modifications

Model Changes

Model	New/Modified Fields	Purpose
Session	useCaseId (FK), phase (enum), currentApproachId (FK), meta (JSONB)	Link to use case, track phase, AI context
UseCase	id, title, prompt, category, tags, templateStyle, createdBy, createdAt	Store reusable prompts/templates
Task	contentGuidance (string), aiPrompt (text), aiResponse (text)	Guide user content, enable AI feedback loop
Post	(link to Task)	Store user submissions

Example Sequelize/TypeORM Additions

// Session Model
@AllowNull(true)
@ForeignKey(() => UseCase)
@Column(DataType.UUID)
useCaseId: string;

@AllowNull(false)
@Default('ideation')
@Column(DataType.ENUM('ideation', 'approaches', 'tasks', 'submission'))
phase: string;

@AllowNull(true)
@ForeignKey(() => Approach)
@Column(DataType.UUID)
currentApproachId: string;

@AllowNull(true)
@Column(DataType.JSONB)
meta: any;

// UseCase Model
@PrimaryKey
@Default(DataType.UUIDV4)
@Column(DataType.UUID)
id: string;
@Column(DataType.STRING)
title: string;
@Column(DataType.TEXT)
prompt: string;
@Column(DataType.STRING)
category: string;
@Column(DataType.ARRAY(DataType.STRING))
tags: string[];
@Column(DataType.STRING)
templateStyle: string;
@Column(DataType.UUID)
createdBy: string;

// Task Model
@Column(DataType.TEXT)
contentGuidance: string;
@Column(DataType.TEXT)
aiPrompt: string;
@Column(DataType.TEXT)
aiResponse: string;

Controller/Service Modifications

• Session Creation: Allow linking to a use case (useCaseId). Store initial phase as ideation.
• Phase Transition: On phase change:
  • If moving to approaches, query for the most relevant use case, store in Session.meta, call AI, store selected approach.
  • If moving to tasks, for each user, call AI with their answers, store generated tasks with contentGuidance.
• Approach/Task Generation:
  • generateApproachForSession(sessionId): Loads session, ideation, use case prompt, calls AI, stores result, updates currentApproachId.
  • generateTasksForSession(sessionId): For each user, calls AI with their answers, stores tasks with contentGuidance, aiPrompt, aiResponse.
• Use Case Management: Admin endpoints to create/update/delete use cases.
• Task Submission: Require users to submit content as per contentGuidance, store submission in Post model, linked to Task.

Example Service Pseudocode

async generateApproachForSession(sessionId: string) {
  // 1. Load session, ideation, use case prompt (from meta or UseCase)
  // 2. Call AI with context
  // 3. Store best approach, update session.currentApproachId
}

async generateTasksForSession(sessionId: string) {
  // 1. For each user, get their answers
  // 2. Call AI with approach, answers, use case prompt
  // 3. Store tasks with contentGuidance, aiPrompt, aiResponse
}

---

5. Summary

This architecture enables:

• Highly relevant, engaging, and collaborative sessions.
• Use case-driven, context-aware AI generation for approaches and tasks.
• Realistic, actionable, and content-sharing tasks for all users.
• Extensible admin dashboard for use case management and analytics.