Sessions¶

Sessions represent live events (games, practices, training) that can be logged, streamed, and analyzed.

Concepts¶

Concept	Description
Session	A time-bounded event with logging, streaming, and timeline
Session Form	Template defining the log entry schema
Log	Structured entry during a session
Clip	Video segment captured from stream
Timeline	Chronological view of logs/clips as files

Session Lifecycle¶

Draft → InProgress → Completed

Status	Description
`Draft`	Created but not started
`InProgress`	Active logging/streaming
`Completed`	Ended, ready for analysis

Types¶

From types/sessions.ts:

interface Session {
  id: string;
  organizationSlug: string;
  teamId: string;
  name: string;
  status: SessionStatus;
  formId?: string;
  createdAt: string;
  startedAt?: string;
  endedAt?: string;
}

type SessionStatus = "Draft" | "InProgress" | "Completed";

interface Log {
  id: string;
  sessionId: string;
  data: Record<string, unknown>;
  createdAt: string;
}

interface Clip {
  id: string;
  sessionId: string;
  startTime: string;
  endTime: string;
  url?: string;
}

interface TimelineItem {
  id: string;
  type: "log" | "clip";
  timestamp: string;
  data: Record<string, unknown>;
}

Hooks¶

useSessions¶

hooks/sessions/use-sessions.ts

List and create sessions for an organization.

const { 
  sessions,        // Session[]
  isLoading,
  createSession    // (data: CreateSessionData) => Promise<Session>
} = useSessions(organizationSlug);

API Calls: - GET /api/v1/actions/sessions - List sessions - POST /api/v1/actions/sessions - Create session

useSession¶

hooks/sessions/use-session.ts

Manage a single session with all operations.

const {
  session,         // Session
  logs,            // Log[]
  clips,           // Clip[]
  timeline,        // TimelineItem[]
  startSession,    // () => Promise<void>
  endSession,      // () => Promise<void>
  deleteSession,   // () => Promise<void>
  createLog,       // (data) => Promise<Log>
  createClip       // (data) => Promise<Clip>
} = useSession(organizationSlug, sessionId);

API Calls: - GET /sessions/{id} - Session detail - GET /sessions/{id}/logs - Session logs - GET /sessions/{id}/clips - Session clips - GET /sessions/{id}/timeline - Timeline items - POST /sessions/{id}/start - Start session - POST /sessions/{id}/end - End session - POST /sessions/{id}/delete - Delete session - POST /sessions/{id}/logs/create - Create log - POST /sessions/{id}/clips/create - Create clip

useSessionForm¶

hooks/sessions/use-session-form.ts

Manage a single form template.

const {
  form,            // SessionForm
  updateForm,      // (data) => Promise<void>
  deleteForm       // () => Promise<void>
} = useSessionForm(organizationSlug, formId);

useOrganizationSessionForms¶

hooks/sessions/use-organization-session-forms.ts

List and create form templates.

const {
  forms,           // SessionForm[]
  createForm       // (data: CreateSessionFormData) => Promise<SessionForm>
} = useOrganizationSessionForms(organizationSlug);

Session Forms¶

Forms define the schema for logging during sessions.

Form Builder¶

components/forms/sessions/session-form-builder.tsx

Visual editor for creating form schemas: - Add/remove fields - Define field types (text, number, select, etc.) - Set validation rules - Preview form

Dynamic Form Renderer¶

components/forms/sessions/dynamic-form-renderer.tsx

Renders a form based on the schema defined by the form builder.

Pages¶

Sessions Overview¶

/portal/[slug]/[teamID]/sessions

Tutorial cards introducing sessions workflow.

Session Management¶

/portal/[slug]/[teamID]/sessions/manage

// Lists all sessions with actions
const { sessions } = useSessions(organizationSlug);

return <SessionsListTable sessions={sessions} />;

Create Session¶

/portal/[slug]/[teamID]/sessions/new

Uses CreateSessionWithForm component: 1. Select a form template 2. Enter session name 3. Create session (Draft status)

Session Detail¶

/portal/[slug]/[teamID]/sessions/[sessionID]

Three-tab interface:

Logging Tab¶

SessionLogger - Form for creating logs
SessionLogsTable - Log history

Streaming Tab¶

CameraSelector - Choose camera
StreamControls - Start/stop, detection toggles
VideoCanvas - Live video with overlays
CameraInfoCard - Camera metadata

Timeline Tab¶

TimelineTable - Chronological log/clip list
"Embed Current Timeline" button

Form Templates¶

/portal/[slug]/[teamID]/sessions/forms

List and manage form templates.

/portal/[slug]/[teamID]/sessions/forms/new

Create new form template with builder.

Embedding Timeline¶

The session detail page can embed timeline items for AI context:

const handleEmbedTimeline = async () => {
  // Fetch each timeline item's full data
  const files = await Promise.all(
    timeline.map(async (item) => {
      const response = await fetch(`/sessions/${sessionId}/logs/${item.id}`);
      const data = await response.json();
      return new File([JSON.stringify(data)], `${item.id}.json`);
    })
  );

  // Upload to embeddings
  await uploadFiles(files);

  // Mark tutorial step complete
  completeSessionsStep("embedContext");
};

Components¶

SessionsListTable¶

components/tables/sessions/sessions-list-table.tsx

Displays sessions with: - Name, status, dates - Actions (view, start, end, delete)

SessionLogsTable¶

components/tables/sessions/session-logs-table.tsx

Displays logs with expandable details.

TimelineTable¶

components/tables/sessions/timeline-table.tsx

Chronological view with type indicators.

SessionLogger¶

components/forms/sessions/session-logger.tsx

Live logging interface bound to session form schema.

Workflow Example¶

Create Form Template
Go to /sessions/forms/new
Define fields (player, action, notes, etc.)
Save template
Create Session
Go to /sessions/new
Select form template
Name session (e.g., "Practice - Jan 15")
Start Session
Open session detail
Click "Start Session"
Status changes to InProgress
Log Events
Use Logging tab
Fill out form for each event
Logs appear in table
Stream Video (optional)
Switch to Streaming tab
Select camera
Start streaming
Create clips of key moments
End Session
Click "End Session"
Status changes to Completed
Embed for AI
Go to Timeline tab
Click "Embed Current Timeline"
Data becomes available for chat/training