erDiagram
    INSTITUTIONS {
        uuid institution_id PK
        string name
        string address
        timestamp created_at
    }
    ROLES {
        uuid role_id PK
        string name
    }
    USERS {
        uuid user_id PK
        string email
        string full_name
        uuid institution_id FK
        uuid role_id FK
        boolean active
        timestamp created_at
    }
    CLASSES {
        uuid class_id PK
        string name
        uuid institution_id FK
    }
    SUBJECTS {
        uuid subject_id PK
        string name
        uuid class_id FK
    }
    ATTENDANCE {
        uuid attendance_id PK
        uuid student_id FK
        uuid class_id FK
        uuid subject_id FK
        timestamp recorded_at
        string status
        string method
        uuid recorded_by FK
    }
    CURRICULUM_ACTIVITIES {
        uuid activity_id PK
        string title
        text description
        date due_date
        uuid created_by FK
    }
    ACTIVITY_ASSIGNMENTS {
        uuid assignment_id PK
        uuid activity_id FK
        uuid class_id FK
        uuid student_id FK
        string status
        timestamp assigned_at
    }
    AUDIT_LOGS {
        uuid log_id PK
        uuid user_id FK
        string action
        text metadata
        timestamp created_at
    }

    INSTITUTIONS ||--o{ USERS : has
    ROLES ||--o{ USERS : defines
    INSTITUTIONS ||--o{ CLASSES : owns
    CLASSES ||--o{ SUBJECTS : contains
    CLASSES ||--o{ USERS : students_in
    USERS ||--o{ ATTENDANCE : records
    SUBJECTS ||--o{ ATTENDANCE : for_subject
    USERS ||--o{ CURRICULUM_ACTIVITIES : creates
    CURRICULUM_ACTIVITIES ||--o{ ACTIVITY_ASSIGNMENTS : assigned_to
    USERS ||--o{ AUDIT_LOGS : performs

flowchart TD
  A[Teacher or QR Scanner] --> B{Is QR valid}
  B -->|Yes| C[Lookup student and class]
  B -->|No| D[Manual entry by teacher]
  C --> E[Record attendance entry]
  D --> E
  E --> F{Is duplicate}
  F -->|Yes| G[Resolve duplicate and log]
  F -->|No| H[Persist attendance and notify student]
  H --> I[Update attendance reports]

flowchart LR
  T[Teacher creates activity] --> Chooser{Target audience}
  Chooser -->|Class| AssignClass[Assign to class]
  Chooser -->|Students| AssignStudents[Assign to students]
  AssignClass --> Notify[Notify students]
  AssignStudents --> Notify
  Notify --> Submit[Students submit or mark complete]
  Submit --> Review[Teacher reviews and grades]
  Review --> Update[Update student activity status and reports]

flowchart TD
  Admin[Admin creates user] --> Invite[Send invitation email]
  Invite --> Register[User registers and sets password]
  Register --> Link[Assign role and link to institution/class]
  Link --> Login[User logs in]
  Login --> FirstTime{First time login}
  FirstTime -->|Yes| Onboard[Redirect to onboarding and profile setup]
  FirstTime -->|No| Dashboard[Redirect to dashboard]