# tranphuoctin/examguardapp architecture

> Architecture diagram of the GitHub repository tranphuoctin/examguardapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tranphuoctin/examguardapp
- Repository: https://github.com/tranphuoctin/examguardapp

## Overview

Based on our analysis of the file structure and the README, Exam Guardian is a Flutter-based, multi-platform online examination app with advanced proctoring features (such as real‑time face monitoring and app switching detection). The architecture is modular and leverages clear separation of concerns via the Flutter Bloc pattern along with dedicated directories for features, data repositories, and core services.

##### Project Type & Purpose
- This is a full-stack Flutter application (client-side heavy) with multi-platform support (mobile, desktop, web) meant for secure online examinations.
- Its primary goal is to deliver a secure exam environment with interactive exam interfaces for students, proctoring features (e.g., face monitoring), and administration/teacher management modules.

##### Key Components
a. User Interface (UI) Layer:
- Represented by the Flutter frontend in the “lib” directory.
- Distinguish modules for different user roles: Student, Teacher, Admin, Authentication, and Common screens (splash, profile, homepage, etc.).
- That UI components interact with feature-specific views (e.g., exam interfaces, monitoring screens, login pages).

b. State Management Layer:
- Incorporate the Bloc/Cubit components (under various feature directories like “features/auth/cubit”, “features/student/exam/cubit”, etc.).
- That UI components dispatch events to these blocs, which govern state updates and trigger further actions.

c. Data & Repository Layer:
- Repositories listed in the “lib/data” and feature-specific repositories (i.e., auth_repository, exam_repository, cheating_repository, etc.).
- These components interface between the state management layer and the underlying data sources or external APIs.
- Use of network communication utilities (using Dio as indicated in “lib/configs/dio_client.dart”).

d. Service Layer:
- Services under the “lib/services” directory such as:
- Face Detection Service (integrates with ML Kit likely for real-time proctoring)
- Notification Service
- Monitoring Log Service
- Socket Service (for real-time interactions)
- How these services feed data to the Bloc layer or repository layer for handling live exam conditions.

e. Local Storage & Configuration:
- How Shared Preferences (shown in “lib/utils/share_preference”) are used for storing tokens (JWT authentication) and user configurations.

f. Platform-specific Layers:
- Platform-specific directories such as “android”, “ios”, “linux”, “macos”, “web”, and “windows”. This indicates that the app has platform-specific build configurations.
- You may simply denote these as different deployment targets but focus on their unified core Flutter code under “lib”.

##### Architectural Patterns & Design Principles
- Use of the Bloc pattern for state management to enforce separation of concerns.
- Modular organization of the project: distinct “features” directories (e.g., auth, student, teacher) representing different bounded contexts.
- Use of service and repository patterns for data fetching and external integrations.
- Rectangles for UI components and modules.
- Parallelograms for data repositories/services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User("User"):::ui

    %% UI Layer
    subgraph "UI Layer"
        UI_Splash("Splash Screen"):::ui
        UI_Login("Login Page"):::ui
        UI_Student("Student Homepage"):::ui
        UI_Teacher("Teacher Homepage"):::ui
        UI_Admin("Admin Homepage"):::ui
    end

    %% State Management (Bloc)
    subgraph "State Management (Bloc)"
        Bloc_Auth("Auth Bloc"):::bloc
        Bloc_Login("Login Bloc"):::bloc
        Bloc_Student("Student Exam Bloc"):::bloc
        Bloc_Monitoring("Exam Monitoring Bloc"):::bloc
        Bloc_Teacher("Teacher Exams Bloc"):::bloc
        Bloc_Admin("Admin Bloc"):::bloc
    end

    %% Repository & Data Layer
    subgraph "Repository & Data Layer"
        Repo_Auth("Auth Repository"):::repo
        Repo_Exam("Exam Repository"):::repo
        Repo_Cheating("Cheating Repository"):::repo
        Repo_Noti("Notification Repository"):::repo
        Repo_User("User Repository"):::repo
        Repo_Password("Password Reset Repository"):::repo
        Repo_Dio("Dio Client"):::repo
    end

    %% Service Layer
    subgraph "Service Layer"
        Service_Face("Face Detection Service"):::service
        Service_Noti("Notification Service"):::service
        Service_Monitor("Monitoring Log Service"):::service
        Service_Socket("Socket Service"):::service
        Service_WindowPip("Window Pip Service"):::service
    end

    %% Local Storage & Configuration
    subgraph "Local Storage & Configuration"
        Storage_SP("Shared Preferences"):::storage
        Storage_TokenCubit("Token Cubit"):::storage
        Storage_TokenState("Token State"):::storage
        Config_App("App Config"):::storage
        Config_Colors("App Colors"):::storage
        Config_Animations("App Animations"):::storage
    end

    %% Platform-specific Build Configurations
    subgraph "Platform-specific Build Configurations"
        Platform("Platform Build Configurations"):::platform
    end

    %% Connections: User to UI Layer
    User --> UI_Splash
    User --> UI_Login
    User --> UI_Student
    User --> UI_Teacher
    User --> UI_Admin

    %% Connections: UI Layer to State Management (Bloc)
    UI_Login -->|"triggers"| Bloc_Auth
    UI_Login -->|"triggers"| Bloc_Login
    UI_Student -->|"triggers"| Bloc_Student
    UI_Student -->|"triggers"| Bloc_Monitoring
    UI_Teacher -->|"triggers"| Bloc_Teacher
    UI_Admin -->|"triggers"| Bloc_Admin

    %% Connections: State Management (Bloc) to Repository & Data Layer
    Bloc_Auth -->|"calls"| Repo_Auth
    Bloc_Login -->|"calls"| Repo_Auth
    Bloc_Student -->|"calls"| Repo_Exam
    Bloc_Monitoring -->|"calls"| Repo_Cheating
    Bloc_Teacher -->|"calls"| Repo_Exam
    Bloc_Admin -->|"calls"| Repo_User

    %% Connections: Repository & Data Layer to Network & Local Storage
    Repo_Auth -->|"uses"| Repo_Dio
    Repo_Exam -->|"uses"| Repo_Dio
    Repo_Cheating -->|"uses"| Repo_Dio
    Repo_Noti -->|"uses"| Repo_Dio
    Repo_Password -->|"uses"| Repo_Dio
    Repo_Auth -->|"persists"| Storage_SP

    %% Connections: Local Storage interactions
    Bloc_Login -->|"updates"| Storage_TokenCubit
    Storage_TokenCubit -->|"reads/writes"| Storage_SP

    %% Connections: UI Configurations
    UI_Splash -->|"applies"| Config_App
    UI_Splash -->|"applies"| Config_Colors
    UI_Splash -->|"applies"| Config_Animations

    %% Connections: State Management to Service Layer
    Bloc_Student -->|"monitors"| Service_Face
    Bloc_Auth -->|"notifies"| Service_Noti
    Bloc_Admin -->|"logs"| Service_Monitor
    Bloc_Monitoring -->|"communicates"| Service_Socket
    Bloc_Teacher -->|"enables"| Service_WindowPip

    %% Connections: UI Layer to Platform-specific Configurations
    UI_Splash --> Platform
    UI_Login --> Platform
    UI_Student --> Platform
    UI_Teacher --> Platform
    UI_Admin --> Platform

    %% Click Events for UI Layer
    click UI_Splash "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/splash/screens/splash_screen.dart"
    click UI_Login "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/auth/view/login_page.dart"
    click UI_Student "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/student/homepage/view/student_homepage_view.dart"
    click UI_Teacher "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/teacher/homepage/view/teacher_homepage_view.dart"
    click UI_Admin "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/admin/view/admin_homepage_view.dart"

    %% Click Events for State Management (Bloc)
    click Bloc_Auth "https://github.com/tranphuoctin/examguardapp/tree/master/lib/features/auth/cubit"
    click Bloc_Login "https://github.com/tranphuoctin/examguardapp/tree/master/lib/features/login/cubit"
    click Bloc_Student "https://github.com/tranphuoctin/examguardapp/tree/master/lib/features/student/exam/cubit"
    click Bloc_Monitoring "https://github.com/tranphuoctin/examguardapp/tree/master/lib/features/student/exam_monitoring/cubit"
    click Bloc_Teacher "https://github.com/tranphuoctin/examguardapp/tree/master/lib/features/teacher/exams/cubit"
    click Bloc_Admin "https://github.com/tranphuoctin/examguardapp/tree/master/lib/features/admin/cubit"

    %% Click Events for Repository & Data Layer
    click Repo_Auth "https://github.com/tranphuoctin/examguardapp/blob/master/lib/data/auth_repository.dart"
    click Repo_Exam "https://github.com/tranphuoctin/examguardapp/blob/master/lib/data/exam_repository.dart"
    click Repo_Cheating "https://github.com/tranphuoctin/examguardapp/blob/master/lib/data/cheating_repository.dart"
    click Repo_Noti "https://github.com/tranphuoctin/examguardapp/blob/master/lib/data/noti_repository.dart"
    click Repo_User "https://github.com/tranphuoctin/examguardapp/blob/master/lib/data/user_repository.dart"
    click Repo_Password "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/auth/repository/password_reset_repository.dart"
    click Repo_Dio "https://github.com/tranphuoctin/examguardapp/blob/master/lib/configs/dio_client.dart"

    %% Click Events for Service Layer
    click Service_Face "https://github.com/tranphuoctin/examguardapp/blob/master/lib/services/face_detection_service.dart"
    click Service_Noti "https://github.com/tranphuoctin/examguardapp/blob/master/lib/services/notification_service.dart"
    click Service_Monitor "https://github.com/tranphuoctin/examguardapp/blob/master/lib/services/monitoring_log_service.dart"
    click Service_Socket "https://github.com/tranphuoctin/examguardapp/blob/master/lib/services/socket_service.dart"
    click Service_WindowPip "https://github.com/tranphuoctin/examguardapp/blob/master/lib/features/teacher/exams/services/window_pip_service.dart"

    %% Click Events for Local Storage & Configuration
    click Storage_SP "https://github.com/tranphuoctin/examguardapp/blob/master/lib/utils/share_preference/shared_preference.dart"
    click Storage_TokenCubit "https://github.com/tranphuoctin/examguardapp/blob/master/lib/utils/share_preference/token_cubit.dart"
    click Storage_TokenState "https://github.com/tranphuoctin/examguardapp/blob/master/lib/utils/share_preference/token_state.dart"
    click Config_App "https://github.com/tranphuoctin/examguardapp/blob/master/lib/configs/app_config.dart"
    click Config_Colors "https://github.com/tranphuoctin/examguardapp/blob/master/lib/configs/app_colors.dart"
    click Config_Animations "https://github.com/tranphuoctin/examguardapp/blob/master/lib/configs/app_animations.dart"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef bloc fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef repo fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef service fill:#ffccbc,stroke:#bf360c,stroke-width:2px;
    classDef storage fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef platform fill:#cfd8dc,stroke:#37474f,stroke-width:2px;
```
