# najat-ttt/sams_basic architecture

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

- Interactive diagram: https://gitdiagram.com/najat-ttt/sams_basic
- Repository: https://github.com/najat-ttt/sams_basic

## Overview

##### Project Type and Purpose
- This is a full-stack, cross-platform mobile application (“SAMS”) built in Flutter (Dart) targeting Android, iOS, Web, Windows, Linux, and macOS.
- It uses Firebase as its backend (Authentication & Firestore) and several on-device plugins for local storage and file export.
- Purpose: enable teachers to log in, mark and review student attendance, and export attendance data as CSV/PDF.

##### High-Level Architecture Components
a. Client (Flutter UI)
- Entry point: lib/main.dart
- Pages: login_page (login, signup, forgot_password), profile_page (dashboard, attendance, reports, schedule, attendance statistics)
- Presentation layer: Widgets, routing, UI state management (setState/BLoC/Cubit if used)
b. Service Layer
- FirebaseAuthService: handles sign-in, sign-up, password reset via Firebase Authentication SDK
- FirestoreService: CRUD operations for attendance records, user profiles, courses
- LocalStorageService: shared_preferences for caching simple key-value data (e.g., auth tokens, user prefs)
- ExportService: pdf and excel packages to generate reports, open_file & path_provider to save/open file on device
- ImageService: image_picker plugin for any profile images or attachments
c. External Backend Services
- Firebase Authentication (user management)
- Firebase Firestore (NoSQL cloud database for attendance, course, user data)
d. Platform Embedding & Plugins
- Android (android/…), iOS (ios/…), Web (web/…), macOS, Linux, Windows folders: Flutter engine integration, native C++/Swift/Kotlin code
- Generated plugin registrants and platform channels for image_picker, pdf, excel, open_file, path_provider

##### Relationships and Data Flow
- Flutter UI → calls Service Layer (Dart classes) → SDK interface → Firebase (Auth or Firestore)
- On login: UI invokes FirebaseAuthService.signIn() → Firebase Auth → returns user credentials → cached in shared_preferences
- On attendance mark/fetch: UI invokes FirestoreService.[get/put] → Firestore
- On export: UI invokes ExportService → uses pdf/excel libs → writes file via path_provider → opens via open_file

##### Architectural Patterns and Design Principles
- Layered architecture: Presentation (Widgets) → Domain/Services (business logic) → Data (Firebase & local storage)
- Single Responsibility: separate service classes for Auth, Firestore, Export, LocalStorage, Image handling
- Dependency Injection: if used (e.g., Provider, GetIt) to supply services to the UI
- Flutter plugin pattern: platform-specific code isolated in android/, ios/, etc.

- Top row: Platforms (Android, iOS, Web, macOS, Linux, Windows) feeding into Flutter engine
- Right side: External cloud services (Auth, Firestore)
- Bottom: Device Storage (shared_preferences, local filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platforms
    subgraph "Platforms"
        AAndroid["Android"]:::platform
        AIos["iOS"]:::platform
        AWeb["Web"]:::platform
        AMac["macOS"]:::platform
        ALinux["Linux"]:::platform
        AWindows["Windows"]:::platform
    end
    AAndroid & AIos & AWeb & AMac & ALinux & AWindows -->|runs on| FE["Flutter Engine"]:::platform

    %% Flutter App Layers
    FE --> FA["Flutter App"]:::frontend
    subgraph "Flutter App"
        direction TB
        subgraph "Presentation Layer"
            direction TB
            Main["Main"]:::frontend
            Login["Login Page"]:::frontend
            Signup["Signup Page"]:::frontend
            Forgot["ForgotPassword Page"]:::frontend
            Profile["Profile Page"]:::frontend
            Dashboard["Dashboard Page"]:::frontend
            Attendance["Attendance Page"]:::frontend
            Reports["Reports Page"]:::frontend
            Schedule["Schedule Page"]:::frontend
        end
        subgraph "Service Layer"
            direction TB
            AuthS["FirebaseAuthService"]:::service
            FireS["FirestoreService"]:::service
            LocalS["LocalStorageService"]:::service
            ExportS["ExportService"]:::service
            ImageS["ImageService"]:::service
        end
        subgraph "Plugin Layer"
            direction TB
            ImgP["image_picker"]:::plugin
            PdfE["pdf/excel"]:::plugin
            PathP["path_provider"]:::plugin
            OpenF["open_file"]:::plugin
        end
    end

    %% External Services
    subgraph "External Cloud Services"
        AuthExt["Firebase Authentication"]:::external
        FireExt["Firebase Firestore"]:::external
    end

    %% Device Storage
    subgraph "Device Storage"
        SharedP["Shared Preferences"]:::plugin
        LocalFS["Local File System"]:::plugin
    end

    %% Data Flows
    Login -->|"signIn() / signUp() / resetPassword()"| AuthS
    Signup -->|"signUp()"| AuthS
    Forgot -->|"resetPassword()"| AuthS
    AuthS -->|"signIn()"| AuthExt
    AuthS -->|"cacheToken()"| LocalS
    LocalS -->|"get()/set()"| SharedP

    Attendance -->|"getAttendance()"| FireS
    FireS -->|"get()/set()"| FireExt
    Reports -->|"generateReport()"| ExportS
    ExportS -->|"generatePDF() / generateExcel()"| PdfE
    ExportS -->|"write()"| PathP
    PathP -->|"open()"| OpenF
    PathP -->|stores| LocalFS
    OpenF -->|opens| LocalFS

    Profile -->|"pickImage()"| ImageS
    ImageS -->|invokes| ImgP

    %% Click Events
    click Main "https://github.com/najat-ttt/sams_basic/blob/master/lib/main.dart"
    click Login "https://github.com/najat-ttt/sams_basic/blob/master/lib/login_page/login_page.dart"
    click Signup "https://github.com/najat-ttt/sams_basic/blob/master/lib/login_page/signup_page.dart"
    click Forgot "https://github.com/najat-ttt/sams_basic/blob/master/lib/login_page/forgot_password_page.dart"
    click Profile "https://github.com/najat-ttt/sams_basic/blob/master/lib/profile_page/profile_page.dart"
    click Dashboard "https://github.com/najat-ttt/sams_basic/blob/master/lib/profile_page/dashboard_page.dart"
    click Attendance "https://github.com/najat-ttt/sams_basic/blob/master/lib/profile_page/attendance_page.dart"
    click Reports "https://github.com/najat-ttt/sams_basic/blob/master/lib/profile_page/reports_page.dart"
    click Schedule "https://github.com/najat-ttt/sams_basic/blob/master/lib/profile_page/schedule_page.dart"
    click AAndroid "https://github.com/najat-ttt/sams_basic/blob/master/android/app/src/main/kotlin/com/example/untitled/MainActivity.kt"
    click AAndroid "https://github.com/najat-ttt/sams_basic/blob/master/android/app/google-services.json"
    click AIos "https://github.com/najat-ttt/sams_basic/blob/master/ios/Runner/AppDelegate.swift"
    click AWeb "https://github.com/najat-ttt/sams_basic/blob/master/web/index.html"
    click AWeb "https://github.com/najat-ttt/sams_basic/blob/master/web/manifest.json"
    click ALinux "https://github.com/najat-ttt/sams_basic/blob/master/linux/flutter/generated_plugin_registrant.cc"
    click AMac "https://github.com/najat-ttt/sams_basic/blob/master/macos/Flutter/GeneratedPluginRegistrant.swift"
    click AWindows "https://github.com/najat-ttt/sams_basic/blob/master/windows/flutter/generated_plugin_registrant.cc"
    click FA "https://github.com/najat-ttt/sams_basic/blob/master/pubspec.yaml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef service fill:#E0F7DA,stroke:#2E7D32,stroke-width:1px
    classDef plugin fill:#FFF3CD,stroke:#FFB300,stroke-width:1px
    classDef external fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px
    classDef platform fill:#E0E0E0,stroke:#424242,stroke-width:1px
```
