# Teams & Classrooms Module

## Purpose
Teachers create **Teams (Groups)** to organize students into cohorts, and **Classroom Instances** to track actual lesson delivery (physical or virtual classroom sessions).

## Key Models

### Team (`app/Models/Team.php`)
- Uses `HasTranslations` — `name` is translatable
- **Fields:** `teacher_id`, `name` (json), `picture`
- **Relationships:**
  - `teacher()` → BelongsTo User (teacher owner)
  - `students()` → BelongsToMany User (via `TeamUser` pivot)
  - `classroomInstances()` → HasMany ClassroomInstance
  - `pathSteps()` → HasMany TeamPathStep (ordered learning path)
  - `completedPathSteps()`, `pendingPathSteps()`, `currentStep()` — Scoped path steps
- **Feature:** Creation consumes `no_of_groups` (teacher subscription)
- **Lifecycle events:** `team.created`, `team.updated`, `team.deleted`
- **Scope helper:** `myGroups()` returns teams for current user

### TeamUser (Pivot Model)
- Custom pivot model for `team` <-> `user` (student) relationship
- **Feature:** Creation consumes `no_of_students_per_group` (checks teacher subscription)

### TeamPathStep (`app/Models/TeamPathStep.php`)
- Defines ordered learning path steps for a team
- Linked to assessments (via `assessment_id`)
- States: `pending`, `active`, `completed`

### ClassroomInstance (`app/Models/ClassroomInstance.php`)
- Tracks lesson delivery instances
- **Fields:** `team_id`, `lesson_id`, `teacher_id`, `mode`, `starts_at`, `duration_minutes`, `link`, `address`, `location`, `is_active`
- **Relationships:**
  - `team()` → BelongsTo Team
  - `lesson()` → BelongsTo Lesson
  - `teacher()` → BelongsTo User

## Integration with Assessments

Team learning paths (`TeamPathStep`) link to assessments for structured progression:
- Each path step references an `Assessment` via `assessment_id`
- Steps have status: pending → active → completed
- Group-based assessments (homework, assignments, exams) target specific teams

See [Assessments Module](assessments.md) for assessment types and lifecycle.

## Feature Entitlement

| Feature | Scope | Default Limit |
|---------|-------|---------------|
| `no_of_groups` | Teacher | 5 |
| `no_of_students_per_group` | Teacher | 20 |
| `no_of_allowed_homework_group` | Teacher | 10 |
| `no_of_allowed_assignment_group` | Teacher | 10 |
| `no_of_allowed_exams_group` | Teacher | 5 |

## Business Rules
- Only teachers can own teams
- Students can belong to multiple teams
- Teams have learning paths with ordered assessment-based steps
- Group-based assessments (homework, assignments, exams) consume from group-level feature counters

## Related Workflows
- **[Course → Lesson → Classroom Workflow](../WORKFLOWS.md#9-course--lesson--classroom-workflow)** — Teams and classrooms are part of the broader content delivery workflow