# clyd-dev/bigkas-ai architecture

> Architecture diagram of the GitHub repository clyd-dev/bigkas-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clyd-dev/bigkas-ai
- Repository: https://github.com/clyd-dev/bigkas-ai

## Overview

BIGKAS is a Laravel reading-assessment and intervention platform with a Python ML classifier. A teacher records a learner reading assigned material; the backend transcribes speech, compares it with the passage, classifies reading weaknesses, stores results, and supports targeted follow-up and progress tracking. Student practice and gamification, parent-teacher coordination, administration, and REST APIs are additional product branches. The workflow and ML calls are documented or visible in excerpts; several peripheral controllers and route-to-view connections are unsampled, so those links are not inferred.

Main entry points: [`app/Http/Controllers/AssessmentController.php`](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/AssessmentController.php) (Assessment Management), [`app/Services/MLClassificationService.php`](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/MLClassificationService.php) (ML Classification), [`app/Models/Learner.php`](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Learner.php) (Learner), [`app/Services/InterventionRecommenderService.php`](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/InterventionRecommenderService.php) (Intervention Recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assessment["Assessment Workflow"]
  node_learner[("Learner<br/>[Learner.php]")]
  node_material[("Reading Material")]
  node_assess["Assessment Management"]
  node_assessment_record[("Assessment Records<br/>[Assessment.php]")]
  node_speech["Speech Transcription"]
  node_analysis["Reading Analysis"]
  node_classification["ML Classification"]
  node_ml_service["Python ML API<br/>[app.py]"]
  node_results[("Reading Results")]
end

subgraph group_learning["Learning Support"]
  node_intervention_service["Intervention Recommendations"]
  node_interventions[("Intervention Library<br/>[Intervention.php]")]
  node_intervention_logs[("Intervention Tracking")]
  node_student_practice["Student Practice"]
  node_practice_sessions[("Practice Sessions")]
  node_badges["Badges and XP<br/>[BadgeService.php]"]
end

subgraph group_portals["Role Portals"]
  node_teacher_portal["Teacher Portal"]
  node_parent_portal["Parent Portal"]
  node_messages["Family Messaging"]
end

subgraph group_platform["Platform Services"]
  node_users[("Users and Roles<br/>[User.php]")]
  node_admin["Administration"]
  node_activity[("Activity Logging<br/>[ActivityLog.php]")]
  node_api["REST API<br/>[api.php]"]
end

node_teacher(("Teacher"))
node_browser(("Web Browser"))

node_teacher -->|"records reading"| node_assess
node_assess -->|"transcribes audio"| node_speech
node_assess -->|"analyzes reading"| node_analysis
node_analysis -->|"classifies weakness"| node_classification
node_assess -->|"classifies result"| node_classification
node_classification -.->|"requests prediction"| node_ml_service
node_assess -->|"uses passage"| node_material
node_assess -->|"assesses learner"| node_learner
node_assess -->|"creates assessment"| node_assessment_record
node_assess -.->|"stores analysis"| node_results
node_intervention_service -->|"selects activities"| node_interventions
node_intervention_service -->|"checks outcomes"| node_intervention_logs
node_student_practice -->|"records practice"| node_practice_sessions
node_student_practice -->|"awards progress"| node_badges
node_teacher_portal -.->|"tracks learners"| node_learner
node_parent_portal -->|"views progress"| node_learner
node_parent_portal -->|"reviews assessments"| node_assessment_record
node_messages -->|"notifies users"| node_users
node_messages -->|"logs messages"| node_activity
node_admin -->|"manages users"| node_users
node_admin -->|"logs actions"| node_activity
node_browser -.->|"sends requests"| node_api
node_api -.->|"routes assessment"| node_assess

click node_learner "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Learner.php"
click node_material "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/ReadingMaterial.php"
click node_assess "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/AssessmentController.php"
click node_assessment_record "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Assessment.php"
click node_speech "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/SpeechToTextService.php"
click node_analysis "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/ReadingAnalyzerService.php"
click node_classification "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/MLClassificationService.php"
click node_ml_service "https://github.com/clyd-dev/bigkas-ai/blob/master/ml-service/app.py"
click node_results "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/AssessmentResult.php"
click node_intervention_service "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/InterventionRecommenderService.php"
click node_interventions "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Intervention.php"
click node_intervention_logs "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/InterventionLog.php"
click node_student_practice "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/Student/StudentActivityController.php"
click node_practice_sessions "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/PracticeSession.php"
click node_badges "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/BadgeService.php"
click node_teacher_portal "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/DashboardController.php"
click node_parent_portal "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/Parent/ParentDashboardController.php"
click node_messages "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/Parent/ParentMessageController.php"
click node_users "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/User.php"
click node_admin "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/AdminController.php"
click node_activity "https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/ActivityLog.php"
click node_api "https://github.com/clyd-dev/bigkas-ai/blob/master/routes/api.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_learner,node_material,node_assess,node_assessment_record,node_speech,node_analysis,node_classification,node_ml_service,node_results,node_browser toneBlue
class node_intervention_service,node_interventions,node_intervention_logs,node_student_practice,node_practice_sessions,node_badges toneAmber
class node_teacher_portal,node_parent_portal,node_messages toneMint
class node_users,node_admin,node_activity,node_api toneRose
class node_teacher toneIndigo
```

## Components

### Assessment Workflow

- [Learner](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Learner.php): `app/Models/Learner.php`
- [Reading Material](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/ReadingMaterial.php): `app/Models/ReadingMaterial.php`
- [Assessment Management](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/AssessmentController.php): `app/Http/Controllers/AssessmentController.php`
- [Assessment Records](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Assessment.php): `app/Models/Assessment.php`
- [Speech Transcription](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/SpeechToTextService.php): `app/Services/SpeechToTextService.php`
- [Reading Analysis](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/ReadingAnalyzerService.php): `app/Services/ReadingAnalyzerService.php`
- [ML Classification](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/MLClassificationService.php): `app/Services/MLClassificationService.php`
- [Python ML API](https://github.com/clyd-dev/bigkas-ai/blob/master/ml-service/app.py): `ml-service/app.py`
- [Reading Results](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/AssessmentResult.php): `app/Models/AssessmentResult.php`

### Learning Support

- [Intervention Recommendations](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/InterventionRecommenderService.php): `app/Services/InterventionRecommenderService.php`
- [Intervention Library](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/Intervention.php): `app/Models/Intervention.php`
- [Intervention Tracking](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/InterventionLog.php): `app/Models/InterventionLog.php`
- [Student Practice](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/Student/StudentActivityController.php): `app/Http/Controllers/Student/StudentActivityController.php`
- [Practice Sessions](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/PracticeSession.php): `app/Models/PracticeSession.php`
- [Badges and XP](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Services/BadgeService.php): `app/Services/BadgeService.php`

### Role Portals

- [Teacher Portal](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/DashboardController.php): `app/Http/Controllers/DashboardController.php`
- [Parent Portal](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/Parent/ParentDashboardController.php): `app/Http/Controllers/Parent/ParentDashboardController.php`
- [Family Messaging](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/Parent/ParentMessageController.php): `app/Http/Controllers/Parent/ParentMessageController.php`

### Platform Services

- [Users and Roles](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/User.php): `app/Models/User.php`
- [Administration](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Http/Controllers/AdminController.php): `app/Http/Controllers/AdminController.php`
- [Activity Logging](https://github.com/clyd-dev/bigkas-ai/blob/master/app/Models/ActivityLog.php): `app/Models/ActivityLog.php`
- [REST API](https://github.com/clyd-dev/bigkas-ai/blob/master/routes/api.php): `routes/api.php`

### Other components

- **Teacher**
- **Web Browser**

## Connections

- Teacher → Assessment Management: records reading
- Assessment Management → Speech Transcription: transcribes audio (evidence: `app/Http/Controllers/AssessmentController.php`)
- Assessment Management → Reading Analysis: analyzes reading (evidence: `app/Http/Controllers/AssessmentController.php`)
- Reading Analysis → ML Classification: classifies weakness (evidence: `app/Services/ReadingAnalyzerService.php`)
- Assessment Management → ML Classification: classifies result (evidence: `app/Http/Controllers/AssessmentController.php`)
- ML Classification → Python ML API: requests prediction
- Assessment Management → Reading Material: uses passage (evidence: `app/Http/Controllers/AssessmentController.php`)
- Assessment Management → Learner: assesses learner (evidence: `app/Http/Controllers/AssessmentController.php`)
- Assessment Management → Assessment Records: creates assessment (evidence: `app/Http/Controllers/AssessmentController.php`)
- Assessment Management → Reading Results: stores analysis
- Intervention Recommendations → Intervention Library: selects activities (evidence: `app/Services/InterventionRecommenderService.php`)
- Intervention Recommendations → Intervention Tracking: checks outcomes (evidence: `app/Services/InterventionRecommenderService.php`)
- Student Practice → Practice Sessions: records practice (evidence: `app/Http/Controllers/Student/StudentActivityController.php`)
- Student Practice → Badges and XP: awards progress (evidence: `app/Http/Controllers/Student/StudentActivityController.php`)
- Teacher Portal → Learner: tracks learners
- Parent Portal → Learner: views progress (evidence: `app/Http/Controllers/Parent/ParentDashboardController.php`)
- Parent Portal → Assessment Records: reviews assessments (evidence: `app/Http/Controllers/Parent/ParentDashboardController.php`)
- Family Messaging → Users and Roles: notifies users (evidence: `app/Http/Controllers/Parent/ParentMessageController.php`)
- Family Messaging → Activity Logging: logs messages (evidence: `app/Http/Controllers/Parent/ParentMessageController.php`)
- Administration → Users and Roles: manages users (evidence: `app/Http/Controllers/AdminController.php`)
- Administration → Activity Logging: logs actions (evidence: `app/Http/Controllers/AdminController.php`)
- Web Browser → REST API: sends requests
- REST API → Assessment Management: routes assessment